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 pela sua API quando a mensagem será enviada e para quem.

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 gerado ao criar uma Campaign disparada por API.

Importante

Este endpoint não oferece suporte a Campaigns de e-mail de transação e retorna um erro 400 se o campaign_id pertencer a uma delas.

Para enviar um e-mail de transação, use o endpoint /transactional/v1/campaigns/{campaign_id}/send.

Pré-requisitos

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

Limite de frequência

Ao usar filtros de Connected Audience em sua solicitação, esse endpoint tem um limite de frequência de 250 solicitações por minuto. Caso contrário, se você especificar um external_id, esse endpoint tem um limite de frequência padrão de 250.000 solicitações por hora, compartilhado entre os endpoints documentados em Limites de frequência da API.

Esse endpoint aceita solicitações de API em lote. Uma única solicitação pode incluir qualquer um dos seguintes itens:

• Até 50 recipients por padrão
• Uma Connected Audience de qualquer tamanho

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
29

{
  "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", "url", and optionally "basic_auth_credential",
    [
      {
       "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",
       "basic_auth_credential": (optional, string) the name of the stored basic authentication credential to use when the attachment URL requires a login,
      }
    ]
}

Parâmetros de solicitação

Comportamento de resolução de destinatários

Esta seção explica como a Braze escolhe um perfil de usuário para o envio e o que acontece quando nenhum perfil é 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 nesse endpoint.

• O vetor recipients pode conter até 50 objetos, e 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 caso ele não exista.
• Perfis novos precisam de attributes com send_to_existing_only: false. A Braze executa a criação ou atualização pré-envio a partir do objeto attributes no mesmo destinatário. Se você definir send_to_existing_only como false, mas omitir attributes (ou enviar um objeto vazio), a Braze não preenche os dados do perfil da mesma forma. Nesse caso, você não obtém o comportamento combinado de “criar ou atualizar usuário e depois enviar” para o qual esse padrão foi pensado.
• Endereçamento de e-mail e SMS. Na maioria dos envios de e-mail ou SMS disparados por API para alguém que ainda não está na Braze, inclua os campos de entrega necessários dentro de attributes (por exemplo, email ou os atributos de telefone que seu espaço de trabalho usa para SMS). Você também pode definir ali a associação ao grupo de inscrições ou o status de inscrição quando o estado de aceitação precisar mudar na mesma chamada.
• Elegibilidade da Campaign. Depois que o perfil existir ou for atualizado, o usuário ainda precisa corresponder ao público-alvo da Campaign definido no dashboard e às regras de envio do canal (por exemplo, ter aceitação para e-mail). Caso contrário, a Braze não envia a mensagem.
• 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, ele 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 só envia 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 depois que o empate é resolvido e prioritization retorna 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 conseguir 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, seja essa configuração true ou false.

Se você disparar uma Campaign somente de e-mail para um destinatário identificado por external_user_id ou user_alias, e esse perfil de usuário não tiver endereço de e-mail no momento da chamada, a Braze tenta o envio novamente por até aproximadamente 2 horas. Isso cobre o padrão comum de criar um usuário e definir o endereço de e-mail dele logo em seguida. Para enviar sem postergação, inclua o atributo email dentro de recipients[].attributes, assim o endereço é definido na mesma chamada do disparo.

Nota

O parâmetro segment_id não é compatível com este endpoint. Para direcionar um Segment, configure o Segment nas configurações de público-alvo da Campaign no dashboard da Braze e use "broadcast": true, ou use o parâmetro audience com filtros de público conectado.

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
77

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",
      "basic_auth_credential": "company_basic_auth_credential_name"
    }
  ]
}'

Detalhes da resposta

As respostas dos endpoints de envio de mensagens incluem o dispatch_id da mensagem para referência ao despacho da mensagem. O dispatch_id é o ID do despacho da mensagem, um ID exclusivo para cada transmissão enviada pela Braze. Ao usar esse endpoint, você recebe um único dispatch_id para todo um conjunto 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 de um usuário antes de enviar uma Campaign disparada por API. Ao usar o endpoint campaign/trigger/send, 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.

Dica

Está procurando a versão do Canvas desse endpoint? Confira Envio de mensagens do Canvas usando entrega disparada por API.

Por que o Liquid não renderiza quando eu o coloco diretamente no corpo JSON?

Quando o corpo da sua solicitação é um JSON válido, a Braze avalia qualquer Liquid na carga útil no servidor. Se você incorporar Liquid como strings brutas, coloque essas strings entre aspas e faça o escape delas para que o corpo continue sendo um JSON válido — por exemplo, escape as aspas duplas dentro das strings. Se o corpo falhar na análise JSON, a Braze retorna um 400 antes de avaliar qualquer Liquid. Quando possível, passe valores dinâmicos por meio de trigger_properties em vez de incorporar Liquid diretamente na carga útil.