Envio imediato de mensagens usando apenas a API

Use esse endpoint para enviar mensagens imediatas a usuários designados usando a API da Braze.

Se estiver direcionando a um segmento, um registro da sua solicitação será armazenado no Console de desenvolvedor.

Importante

Se a carga útil final renderizada for maior do que o tamanho máximo permitido pelo serviço correspondente, o envio não será bem-sucedido.

Importante

Ao usar este endpoint para Campaigns da API, o destinatário já deve existir na Braze para que a solicitação seja bem-sucedida. Isso se aplica ao especificar usuários nos parâmetros external_user_ids ou user_aliases.

Criar novos usuários com envios de API

Se você precisar criar um usuário como parte de um envio usando a API, tem duas opções:

Opção 1: Use /users/track e depois envie

Primeiro, crie o usuário com o endpoint /users/track e, em seguida, aguarde a propagação dos dados (geralmente, recomenda-se aguardar alguns minutos) antes de iniciar o envio somente pela API. Observe que a Braze não garante os tempos de processamento de dados em /users/track, portanto, podem ocorrer condições de corrida se você não deixar tempo suficiente entre essas chamadas.

Opção 2: Use uma Campaign disparada por API ou Canvas

Use uma Campaign disparada por API ou um fluxo de trabalho de Canvas. Isso permite que você crie um destinatário, caso ainda não exista um. Essa opção simplifica seus processos de back-end, mas exige que você configure uma Campaign ou um Canvas no dashboard da Braze.

Pré-requisitos

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

Limite de taxa

Ao usar filtros de Connected Audience 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 Connected Audience

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
• Um segmento de qualquer tamanho criado no dashboard da Braze, especificado por seu segment_id
• Um segmento de público de qualquer tamanho, definido na solicitação como um objeto de Connected Audience

Corpo da solicitação

Dica

Certifique-se de incluir objetos de envio de mensagens no corpo da solicitação para concluir suas solicitações.

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
{
   // You will need to include at least one of 'segment_id', 'external_user_ids', and 'audience'
   // Including 'segment_id' will send to members of that segment
   // Including 'external_user_ids' and/or 'user_aliases' will send to those users
   // Including both will send to the provided users if they are in the segment
   "broadcast": (optional, boolean) see broadcast -- defaults to false on 8/31/17, must be set to true if no external_user_ids or aliases are provided,
   "external_user_ids": (optional, array of strings) see external user identifier,
   "user_aliases": (optional, array of user alias object) see user alias,
   "segment_id": (optional, string) see segment identifier,
   "audience": (optional, connected audience object) see connected audience,
   "campaign_id": (optional*, string) *required if you wish to track campaign stats (for example, sends, clicks, bounces, etc). see campaign identifier,
   "send_id": (optional, string) see send identifier,
   "override_frequency_capping": (optional, bool) ignore frequency_capping for campaigns, defaults to false,
   "recipient_subscription_state": (optional, string) use this to send messages to only users who have opted in ('opted_in'), only users who have subscribed or are opted in ('subscribed') or to all users, including unsubscribed users ('all'), the latter being useful for transactional email messaging. Defaults to 'subscribed',
   "messages": {
     "android_push": (optional, android push object),
     "apple_push": (optional, apple push object),
     "content_card": (optional, content card object),
     "email": (optional, email object),
     "kindle_push": (optional, kindle/fireOS push object),
     "web_push": (optional, web push object),
     "webhook": (optional, webhook object),
     "whats_app": (optional, WhatsApp object),
     "sms": (optional, SMS object)
   }
 }

Parâmetros de solicitação

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
curl --location --request POST 'https://rest.iad-01.braze.com/messages/send' \
--data-raw '{
  "broadcast": "false",
  "external_user_ids": "external_user_identifiers",
  "user_aliases": {
    "alias_name": "example_name",
    "alias_label": "example_label"
  },
  "segment_id": "segment_identifier",
  "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"
        }
      }
    ]
  },
  "campaign_id": "campaign_identifier",
  "send_id": "send_identifier",
  "override_frequency_capping": "false",
  "recipient_subscription_state": "all",
  "messages": {
    "android_push": "(optional, Android Push Object)",
    "apple_push": "(optional, Apple Push Object)",
    "content_card": "(optional, Content Card Object)",
    "email": "(optional, Email Object)",
    "kindle_push": "(optional, Kindle/FireOS Push Object)",
    "web_push": "(optional, Web Push Object)"
  }
}'

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, ou seja, o ID exclusivo de cada “transmissão” enviada pela Braze. Para saber mais, consulte Comportamento do Dispatch ID.