Envío de mensajes mediante la REST API

Puedes enviar mensajes desde tu backend en tiempo real utilizando dos puntos finales diferentes de Braze. Cada uno tiene una forma de solicitud diferente: uno requiere el contenido completo del mensaje en la solicitud; el otro requiere un ID de Campaign y envía el contenido definido en el dashboard.

Este enfoque funciona con cualquier canal de mensajería compatible con la API (WhatsApp, correo electrónico, SMS, push, Content Cards, webhooks y más).

Dos formas de enviar

Para obtener información detallada sobre las solicitudes y respuestas, consulta las referencias de los puntos finales Enviar mensajes inmediatamente (solo API) y Enviar Campaigns mediante entrega desencadenada por API.

Opción 1: Enviar con el contenido del mensaje en la solicitud (/messages/send)

Utiliza este punto final cuando desees especificar el contenido completo del mensaje en la solicitud de API. Debes incluir un objeto messages (por ejemplo, messages.whats_app, messages.email o messages.sms). Puedes omitir campaign_id para enviar sin seguimiento de Campaign, o incluir un ID de Campaign de API y message_variation_id en cada mensaje para realizar un seguimiento de los envíos en el dashboard (consulta la referencia del punto final para obtener más detalles).

Requisitos: Clave de API con el permiso messages.send.

Importante

Cada destinatario en external_user_ids debe existir ya en Braze. Para crear usuarios como parte de un envío, utiliza /users/track primero, o utiliza la Opción 2 (Campaign desencadenada por API) en su lugar.

Ejemplo: mensaje de plantilla de 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 obtener la especificación completa del objeto WhatsApp, consulta Objeto WhatsApp.

Nota

El punto final /messages/send solo admite plantillas de WhatsApp con encabezados TEXT o IMAGE. Para DOCUMENT, VIDEO u otros tipos de encabezados multimedia, utiliza el punto final de Campaign desencadenada por API o el panel de Braze.

Ejemplo: correo electrónico

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 otros canales, consulta Objetos de mensajería.

Opción 2: Desencadenar una Campaign con contenido en el dashboard (/campaigns/trigger/send)

Utiliza este punto final cuando el contenido del mensaje se cree en el panel de Braze (Campaign desencadenada por API). Envías un campaign_id obligatorio y los destinatarios; no envías un objeto messages.

Requisitos: Clave de API con el permiso campaigns.trigger.send.

Paso 1: Crear una Campaign desencadenada por API

1. En el panel de Braze, ve a Messaging > Campaigns.
2. Selecciona Create Campaign y, a continuación, API-Triggered Campaign (no “API Campaign”).
3. Añade tu canal de mensajería (WhatsApp, correo electrónico, SMS, etc.) y crea el contenido del mensaje en el dashboard.
4. Anota el Campaign ID (y el Send ID si utilizas varias variantes de mensaje). Los utilizarás en la solicitud de API.

Para obtener más información sobre cómo crear Campaigns desencadenadas por API, consulta Entrega desencadenada por API.

Paso 2: Desencadenar la Campaign a través de la API

Envía una solicitud POST a /campaigns/trigger/send con campaign_id y recipients (o broadcast/audience). No incluyas un objeto messages: el contenido proviene de la Campaign.

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 ver el cuerpo completo de la solicitud (incluidos trigger_properties, send_to_existing_only, attributes, etc.), consulta la referencia del punto final Enviar Campaigns mediante entrega desencadenada por API.

Verifica tu integración

1. Envía una solicitud utilizando una de las opciones anteriores, con tu propio ID de usuario como destinatario.
2. Confirma que el mensaje se ha entregado.
3. Si utilizas la opción 2, comprueba la Campaign en el panel de Braze para confirmar que el envío se ha registrado.

Consideraciones

• Utiliza las características de personalización de Braze para adaptar el contenido cuando sea posible.
• Asegúrate de que tu mensajería cumpla con las normativas pertinentes e incluya las opciones de exclusión voluntaria y los avisos de privacidad necesarios.
• Para obtener más información sobre los puntos finales (programación, desencadenadores de Canvas, etc.), consulta Puntos finales de mensajería.