Envio de mensagens usando a REST API

Você pode enviar mensagens do seu backend em tempo real usando dois endpoints diferentes da Braze. Cada um tem uma forma de requisição diferente: um requer o conteúdo completo da mensagem na requisição; o outro requer um ID de campanha e envia o conteúdo definido no dashboard.

Essa abordagem funciona com qualquer canal de envio de mensagens suportado pela API (WhatsApp, e-mail, SMS, push, Content Cards, webhooks e mais).

Duas maneiras de enviar

Para detalhes completos de requisição e resposta, consulte as referências dos endpoints Enviar mensagens imediatamente (somente API) e Enviar campanhas usando entrega disparada por API.

Opção 1: Enviar com conteúdo da mensagem na requisição (/messages/send)

Use este endpoint quando quiser especificar o conteúdo completo da mensagem na requisição da API. Você deve incluir um objeto messages (por exemplo, messages.whats_app, messages.email ou messages.sms). Você pode omitir campaign_id para enviar sem rastreamento de campanha, ou incluir um ID de campanha da API e message_variation_id em cada mensagem para rastrear envios no dashboard (consulte a referência do endpoint para detalhes).

Obrigatória: chave de API com a permissão messages.send.

Exemplo: mensagem de modelo do WhatsApp

1
2
3
POST YOUR_REST_ENDPOINT/messages/send
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "external_user_ids": ["user123"],
  "messages": {
    "whats_app": {
      "app_id": "YOUR_APP_ID",
      "subscription_group_id": "YOUR_WHATSAPP_SUBSCRIPTION_GROUP_ID",
      "message_type": "template_message",
      "message": {
        "template_name": "new_message_received",
        "template_language_code": "en_US"
      }
    }
  }
}

Para a especificação completa do objeto WhatsApp, consulte Objeto WhatsApp.

Exemplo: e-mail

1
2
3
4
5
6
7
8
9
10
11
{
  "external_user_ids": ["user123"],
  "messages": {
    "email": {
      "app_id": "YOUR_APP_ID",
      "subject": "Your order has shipped",
      "from": "[email protected]",
      "body": "<p>Your order #12345 is on its way.</p>"
    }
  }
}

Para outros canais, consulte Objetos de envio de mensagens.

Opção 2: Disparar uma campanha com conteúdo no dashboard (/campaigns/trigger/send)

Use este endpoint quando o conteúdo da mensagem for construído no dashboard da Braze (campanha disparada por API). Você envia um campaign_id obrigatório e os destinatários; você não envia um objeto messages.

Obrigatória: chave de API com a permissão campaigns.trigger.send.

Etapa 1: Crie uma campanha disparada por API

1. No dashboard da Braze, acesse Messaging > Campaigns.
2. Selecione Create Campaign e depois API-Triggered Campaign (não “API Campaign”).
3. Adicione seu canal de mensagem (WhatsApp, e-mail, SMS, etc.) e construa o conteúdo da mensagem no dashboard.
4. Anote o Campaign ID (e o Send ID, se você usar várias variantes de mensagem). Você usará esses valores na requisição da API.

Para mais informações sobre como construir campanhas disparadas por API, consulte Entrega disparada por API.

Etapa 2: Dispare a campanha via API

Envie uma requisição POST para /campaigns/trigger/send com campaign_id e recipients (ou broadcast/audience). Não inclua um objeto messages — o conteúdo vem da campanha.

1
2
3
POST YOUR_REST_ENDPOINT/campaigns/trigger/send
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
7
8
{
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "recipients": [
    {
      "external_user_id": "user123"
    }
  ]
}

Para o corpo completo da requisição (incluindo trigger_properties, send_to_existing_only, attributes, etc.), consulte a referência do endpoint Enviar campanhas usando entrega disparada por API.

Verifique sua integração

1. Envie uma requisição usando uma das opções acima, com seu próprio ID de usuário como destinatário.
2. Confirme que a mensagem foi entregue.
3. Se estiver usando a Opção 2, verifique a campanha no dashboard da Braze para confirmar que o envio foi registrado.

Considerações

• Use os recursos de personalização da Braze para adaptar o conteúdo quando suportado.
• Garanta que seu envio de mensagens esteja em conformidade com as regulamentações aplicáveis e inclua as opções de descadastramento e os avisos de privacidade exigidos.
• Para mais endpoints (agendamento, gatilhos de Canvas, etc.), consulte Endpoints de envio de mensagens.