Envie mensagens de campanha por meio de entrega disparada por API

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

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

Se estiver direcionando a campanha para um segmento, um registro da sua solicitação será armazenado 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

When specifying a segment or Connected Audience in your request, we apply a rate limit of 250 requests per minute to this endpoint. Otherwise, if specifying an external_id, this endpoint has a default rate limit of 250,000 requests per hour shared between /messages/send, /campaigns/trigger/send, and /canvas/trigger/send, as documented in API rate limits.

Braze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:

• Up to 50 specific external_ids, each with individual message parameters
• A segment of any size created in the Braze dashboard, specified by its segment_id
• An audience segment of any size, defined in the request as a connected audience object

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 will 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' will only send to users in the audience
  "recipients": (optional, array; if not provided and broadcast is not set to `false`, message will send 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 will apply to this user (these key-value pairs will 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 will 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 will be 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 will be 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 objetos pode conter até 50 objetos, sendo que cada objeto contém uma única string external_user_id e um objeto trigger_properties.
• Quando send_to_existing_only for true, a Braze enviará a mensagem apenas para os usuários existentes. No entanto, esse sinalizador não pode ser usado com aliases de usuário.
• Quando send_to_existing_only é false, uma atribuição precisa ser incluída. A Braze criará um usuário com o endereço id e as atribuições antes de enviar a mensagem.

O status do grupo de inscrições de um usuário pode ser atualizado por meio da inclusão de um parâmetro subscription_groups no objeto attributes. Para obter mais informações, consulte Objeto de atribuições 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 incluirão o endereço dispatch_id da mensagem para referência ao envio da mensagem. O endereço dispatch_id é o ID do envio 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 site 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 atribuições para campanhas

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