Enviar mensajes de campaña mediante entrega desencadenada por API

Utiliza este endpoint para enviar mensajes inmediatos y puntuales a usuarios designados mediante la entrega desencadenada por API.

La entrega desencadenada por API te permite alojar el contenido de los mensajes dentro del panel de Braze, al tiempo que decides mediante tu API cuándo se envía un mensaje y a quién.

Si te diriges a un segmento, se almacena un registro de tu solicitud en la consola para desarrolladores. Para enviar mensajes con este endpoint, debes tener un ID de campaña, que se crea al configurar una campaña desencadenada por API.

Importante

Este endpoint no admite campañas de correo transaccional y devuelve un error 400 si el campaign_id pertenece a una de ellas.

Para enviar un correo transaccional, utiliza el endpoint /transactional/v1/campaigns/{campaign_id}/send.

Requisitos previos

Para utilizar este endpoint, deberás generar una clave de API con el permiso campaigns.trigger.send.

Límite de velocidad

Cuando utilizas filtros de audiencia conectada en tu solicitud, este endpoint tiene un límite de velocidad de 250 solicitudes por minuto. De lo contrario, si especificas un external_id, este endpoint tiene un límite de velocidad predeterminado de 250 000 solicitudes por hora, compartido entre los endpoints documentados en Límites de velocidad de la API.

Este endpoint admite solicitudes de API por lotes. Una solicitud puede incluir cualquiera de los siguientes elementos:

• Hasta 50 recipients de forma predeterminada
• Una audiencia conectada de cualquier tamaño

Cuerpo de la solicitud

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 la solicitud

Comportamiento de resolución de destinatarios

Esta sección explica cómo Braze selecciona un perfil de usuario para el envío y qué sucede cuando no se selecciona un perfil.

El estado del grupo de suscripción de un usuario puede actualizarse incluyendo un parámetro subscription_groups dentro del objeto attributes. Para más detalles, consulta Objeto de atributos de usuario.

Límites de destinatarios y creación de perfiles

Obtén más información sobre cómo funcionan los límites de destinatarios y la creación de perfiles para este endpoint.

• La matriz recipients puede contener hasta 50 objetos, cada uno con una única cadena external_user_id y un objeto trigger_properties.
• Cuando send_to_existing_only es true (el valor predeterminado), Braze envía el mensaje solo a los usuarios existentes.
• Cuando send_to_existing_only es false y se proporciona un objeto attributes, Braze crea un nuevo usuario si no existe ninguno.
• Los perfiles nuevos necesitan attributes con send_to_existing_only: false. Braze ejecuta la creación o actualización previa al envío a partir del objeto attributes en el mismo destinatario. Si estableces send_to_existing_only en false pero omites attributes (o envías un objeto vacío), Braze no hidrata los datos del perfil de la misma manera, por lo que no obtienes el comportamiento combinado de “crear o actualizar el usuario y luego enviar” para el que está pensado este patrón.
• Direccionamiento de correo electrónico y SMS. Para la mayoría de los envíos de correo electrónico o SMS desencadenados por API a alguien que aún no está en Braze, incluye los campos de entrega que necesitas dentro de attributes (por ejemplo, email, o los atributos de teléfono que tu espacio de trabajo utiliza para SMS). También puedes establecer allí la pertenencia al grupo de suscripción o el estado de suscripción cuando el estado de adhesión voluntaria deba cambiar en la misma llamada.
• Elegibilidad para la campaña. Después de que el perfil exista o se actualice, ese usuario aún debe coincidir con el público objetivo de la campaña definido en el panel y con las reglas de envío del canal (por ejemplo, haber dado su adhesión voluntaria al correo electrónico); de lo contrario, Braze no envía el mensaje.
• Establecer send_to_existing_only en false no es compatible con los alias de usuario. No se pueden crear nuevos usuarios solo con alias a través de este endpoint. Para enviar a un usuario que solo tiene alias, este debe existir ya en Braze.

Identificador de correo electrónico y empates de priorización

Cuando identificas destinatarios por correo electrónico, Braze utiliza prioritization. Braze solo envía cuando prioritization devuelve un perfil.

• Si utilizas email como identificador, Braze resuelve el destinatario usando prioritization.
• Si prioritization devuelve un empate, Braze no envía.
• Braze envía después de que se resuelva el empate y prioritization devuelva un perfil. Por ejemplo, si las actualizaciones de perfil cambian los campos de ordenación de un usuario, Braze envía en cuanto prioritization pueda identificar un perfil de forma única (consulta Comportamiento de reintentos y send_to_existing_only).
• Braze tampoco envía cuando prioritization no devuelve ningún perfil.

Comportamiento de reintentos y send_to_existing_only

Descubre qué sucede cuando prioritization no devuelve exactamente un perfil.

• Cuando prioritization no devuelve exactamente un perfil de usuario, Braze reintenta la resolución hasta 40 veces. Este comportamiento de reintento es el esperado.
• La configuración de send_to_existing_only no cambia el comportamiento de empate de prioritization. El mismo comportamiento de empate y reintento se aplica tanto si esta configuración es true como si es false.

Si desencadenas una campaña solo de correo electrónico para un destinatario identificado por external_user_id o user_alias, y ese perfil de usuario no tiene dirección de correo electrónico en el momento de la llamada, Braze reintenta el envío durante aproximadamente 2 horas como máximo. Esto cubre el patrón habitual de crear un usuario y establecer su dirección de correo electrónico en rápida sucesión. Para enviar sin demora, incluye el atributo email dentro de recipients[].attributes para que la dirección se establezca en la misma llamada que el desencadenante.

Nota

El parámetro segment_id no es compatible con este endpoint. Para dirigirte a un segmento, configúralo en la configuración de público objetivo de la campaña en el panel de Braze y utiliza "broadcast": true, o bien utiliza el parámetro audience con filtros de audiencia conectada.

Ejemplo de solicitud

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"
    }
  ]
}'

Detalles de la respuesta

Las respuestas de los endpoints de envío de mensajes incluyen el dispatch_id del mensaje como referencia al envío del mensaje. El dispatch_id es el ID del envío del mensaje, un ID único para cada transmisión enviada desde Braze. Al utilizar este endpoint, recibes un único dispatch_id para todo un conjunto de usuarios por lotes. Para más información sobre dispatch_id, consulta nuestra documentación sobre el comportamiento de Dispatch ID.

Si tu solicitud encuentra un error fatal, consulta Errores y respuestas para ver el código de error y su descripción.

Objeto de atributos para campañas

Braze tiene un objeto de mensajería llamado attributes que te permite añadir, crear o actualizar atributos y valores para un usuario antes de enviarle una campaña desencadenada por API. Al usar el endpoint campaign/trigger/send, esta llamada a la API procesa el objeto de atributos de usuario antes de procesar y enviar la campaña. Esto ayuda a minimizar el riesgo de que se produzcan problemas causados por condiciones de carrera.

Consejo

¿Buscas la versión Canvas de este endpoint? Consulta Enviar mensajes Canvas mediante entrega desencadenada por API.

¿Por qué Liquid no se renderiza cuando lo pongo directamente en el cuerpo JSON?

Cuando el cuerpo de tu solicitud es JSON válido, Braze evalúa en el servidor cualquier Liquid presente en la carga útil. Si incrustas Liquid como cadenas sin procesar, pon esas cadenas entre comillas y escápalas para que el cuerpo siga siendo JSON válido; por ejemplo, escapa las comillas dobles dentro de las cadenas. Si el cuerpo no supera el análisis JSON, Braze devuelve un 400 antes de evaluar cualquier Liquid. Cuando sea posible, pasa los valores dinámicos a través de trigger_properties en lugar de incrustar Liquid directamente en la carga útil.