Envie mensagens de campanha usando a entrega disparada por API

Use esse endpoint para enviar mensagens únicas e imediatas a usuários designados usando a entrega disparada pela API.

O envio disparado pela API permite que você armazene o conteúdo da mensagem dentro do dashboard da Braze e, ao mesmo tempo, determine quando a mensagem será enviada e para quem, usando sua API.

Se você estiver direcionando um segmento, um registro da sua solicitação é armazenado no console de desenvolvedor. Para enviar mensagens com esse endpoint, você deve ter um ID de campanha criado ao criar uma campanha disparada por API.

Pré-requisitos

Para usar esse endpoint, você precisará gerar uma chave de API com a permissão campaigns.trigger.send.

Limite de taxa

Ao usar filtros de público conectado em sua solicitação, aplicamos um limite de taxa de 250 solicitações por minuto para esse endpoint. Caso contrário, se estiver especificando um external_id, esse endpoint terá um limite de taxa padrão de 250.000 solicitações por hora compartilhado entre /messages/send, /campaigns/trigger/send e /canvas/trigger/send, conforme documentado em Limites de taxa da API.

Os endpoints da Braze suportam agrupamento de solicitações da API. Uma única solicitação para os endpoints de envio de mensagens pode alcançar qualquer um dos seguintes itens:

• Até 50 external_ids específicos, cada um com parâmetros de mensagem individuais
• Um segmento de público de qualquer tamanho, definido na solicitação como um objeto de público conectado

Os endpoints da Braze aceitam solicitações de API em lote. Uma única solicitação para os endpoints de envio de mensagens pode alcançar qualquer um dos seguintes itens:

• Até 50 external_ids específicos, cada um com parâmetros de mensagem individuais
• Um segmento de público de qualquer tamanho, definido na solicitação como um objeto de público conectado

Corpo da solicitação

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "campaign_id": (required, string) see campaign identifier,
  "send_id": (optional, string) see send identifier,
  "trigger_properties": (optional, object) personalization key-value pairs that apply to all users in this request,
  "broadcast": (optional, boolean) see broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" is omitted,
  "audience": (optional, connected audience object) see connected audience,
  // Including 'audience' sends to only users in the audience
  "recipients": (optional, array; if not provided and broadcast is not set to `false`, message sends to the entire segment targeted by the campaign)
    [
      {
      // Either "external_user_id" or "user_alias" or "email" is required. Requests must specify only one.
      "user_alias": (optional, user alias object) user alias of user to receive message,
      "external_user_id": (optional, string) external identifier of user to receive message,
      "email": (optional, string) email address of user to receive message,
      "prioritization": (optional, array) prioritization array; required when using email,
      "trigger_properties": (optional, object) personalization key-value pairs that apply to this user (these key-value pairs override any keys that conflict with the parent trigger_properties),
      "send_to_existing_only": (optional, boolean) defaults to true, can't be used with user aliases; if set to `false`, an attributes object must also be included,
      "attributes": (optional, object) fields in the attributes object create or update an attribute of that name with the given value on the specified user profile before the message is sent and existing values are overwritten
    }
  ],
  "attachments": (optional, array) array of JSON objects that define the files you need attached, defined by "file_name" and "url",
    [
      {
       "file_name": (required, string) the name of the file you want to attach to your email, excluding the extension (for example, ".pdf"). Attach files up to 2 MB. This is required if you use "attachments",
       "url": (required, string) the corresponding URL of the file you want to attach to your email. The file name's extension is detected automatically from the URL defined, which should return the appropriate "Content-Type" as a response header. This is required if you use "attachments",
      }
    ]
}

Parâmetros de solicitação

• O vetor de destinatários pode conter até 50 objetos, sendo que cada objeto contém um único identificador de usuário (external_user_id, user_alias ou email) e um objeto trigger_properties opcional.
• Quando send_to_existing_only é true (o padrão), a Braze envia a mensagem apenas para usuários existentes. Se o identificador no objeto de destinatários (external_user_id, user_alias ou email) não corresponder a nenhum usuário existente, a API ainda retorna uma resposta de sucesso 201 com um dispatch_id, mas o envio é cancelado internamente e nenhuma mensagem é entregue. Para external_user_id, o resultado é registrado como Unknown External User ID e nenhum evento Currents é gerado. Quando definido como false e um objeto de atributos é fornecido, a Braze cria um novo usuário se ele não existir. Observe que definir send_to_existing_only como false não é compatível com aliases de usuário — novos usuários apenas com alias não podem ser criados por meio deste endpoint. Para enviar para um usuário apenas com alias, o usuário já deve existir na Braze.

O status do grupo de inscrições de um usuário pode ser atualizado com a inclusão de um parâmetro subscription_groups no objeto attributes. Para saber mais, consulte Objeto de atributos do usuário.

Exemplo de solicitação

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
curl --location --request POST 'https://rest.iad-01.braze.com/campaigns/trigger/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "campaign_id": "campaign_identifier",
  "send_id": "send_identifier",
  "trigger_properties": "",
  "broadcast": false,
  "audience": {
    "AND": [
      {
        "custom_attribute": {
          "custom_attribute_name": "eye_color",
          "comparison": "equals",
          "value": "blue"
        }
      },
      {
        "custom_attribute": {
          "custom_attribute_name": "favorite_foods",
          "comparison": "includes_value",
          "value": "pizza"
        }
      },
      {
        "OR": [
          {
            "custom_attribute": {
              "custom_attribute_name": "last_purchase_time",
              "comparison": "less_than_x_days_ago",
              "value": 2
            }
          },
          {
            "push_subscription_status": {
              "comparison": "is",
              "value": "opted_in"
            }
          }
        ]
      },
      {
        "email_subscription_status": {
          "comparison": "is_not",
          "value": "subscribed"
        }
      },
      {
        "last_used_app": {
          "comparison": "after",
          "value": "2019-07-22T13:17:55+0000"
        }
      }
    ]
  },
  "recipients": [
    {
      "user_alias": {
        "alias_name" : "example_name",
        "alias_label" : "example_label"
      },
      "external_user_id": "external_user_identifier",
      "trigger_properties": "",
      "send_to_existing_only": true,
      "attributes": {
        "first_name" : "Alex"
      }
    }
  ],
  "attachments": [
    {
      "file_name" : "YourFileName",
      "url" : "https://exampleurl.com/YourFileName.pdf"
    }
  ]
}'

Detalhes da resposta

As respostas do endpoint de envio de mensagens incluem o dispatch_id da mensagem para referência ao despacho da mensagem. O dispatch_id é o ID do despacho de mensagens, um ID exclusivo para cada transmissão enviada pela Braze. Ao usar esse endpoint, você recebe um único dispatch_id para um conjunto inteiro de usuários em lote. Para saber mais sobre o dispatch_id, consulte nossa documentação sobre o comportamento do Dispatch ID.

Se sua solicitação encontrar um erro fatal, consulte Erros e respostas para obter o código e a descrição do erro.

Objeto de atributos para campanhas

A Braze tem um objeto de envio de mensagens chamado attributes que permite adicionar, criar ou atualizar atributos e valores para um usuário antes de enviar uma campanha disparada por API. Usar o endpoint campaign/trigger/send como essa chamada de API processa o objeto de atributos do usuário antes de processar e enviar a campanha. Isso ajuda a minimizar o risco de problemas causados por condições de corrida.