Enviar mensagens de Campaign usando entrega disparada por API

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

A entrega disparada por 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 Segment, um registro da sua solicitação é armazenado no Console de desenvolvedor. Para enviar mensagens com esse endpoint, você deve ter um ID de Campaign criado ao criar uma Campaign 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 a esse endpoint. Caso contrário, se estiver especificando um external_id, esse endpoint tem um limite de taxa padrão de 250.000 solicitações por hora compartilhado entre os endpoints documentados em Limites de taxa da API.

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

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

Comportamento de resolução de destinatários

Esta seção explica como a Braze seleciona um perfil de usuário para envio e o que acontece quando um perfil não é selecionado.

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.

Limites de destinatários e criação de perfis

Saiba mais sobre como os limites de destinatários e a criação de perfis funcionam para esse endpoint.

• O vetor recipients 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 é true (o padrão), a Braze envia a mensagem apenas para usuários existentes.
• Quando send_to_existing_only é false e um objeto attributes é fornecido, a Braze cria um novo usuário se ele não existir.
• 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.

Identificador de e-mail e empates de priorização

Quando você identifica destinatários por e-mail, a Braze usa prioritization. A Braze envia apenas quando prioritization retorna um perfil.

• Se você usar email como identificador, a Braze resolve o destinatário usando prioritization.
• Se prioritization retornar um empate, a Braze não envia.
• A Braze envia após o empate ser resolvido e prioritization retornar um perfil. Por exemplo, se atualizações de perfil alterarem os campos de ordenação de um usuário, a Braze envia assim que prioritization puder identificar um perfil de forma única (consulte Comportamento de nova tentativa e send_to_existing_only).
• A Braze também não envia quando prioritization não retorna nenhum perfil.

Comportamento de nova tentativa e send_to_existing_only

Saiba o que acontece quando prioritization não retorna exatamente um perfil.

• Quando prioritization não retorna exatamente um perfil de usuário, a Braze tenta a resolução novamente até 40 vezes. Esse comportamento de nova tentativa é esperado.
• A configuração send_to_existing_only não altera o comportamento de empate de prioritization. O mesmo comportamento de empate e nova tentativa se aplica independentemente de essa configuração ser true ou false.

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 Campaigns

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 Campaign 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 Campaign. Isso ajuda a minimizar o risco de problemas causados por condições de corrida.