Envía mensajes de campaña utilizando la entrega desencadenada por API

Utiliza este punto final para enviar mensajes inmediatos y puntuales a usuarios designados utilizando la entrega desencadenada por la API.

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

Si te diriges a un segmento, se almacenará un registro de tu solicitud en la Consola para desarrolladores. Para enviar mensajes con este punto final, debes tener un ID de campaña creado al crear una campaña desencadenada por la API.

Requisitos previos

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

Límite de velocidad

Al especificar un segmento o Audiencia Conectada en tu solicitud, aplicamos un límite de velocidad de 250 solicitudes por minuto a este punto final. De lo contrario, si se especifica un external_id, este punto final tiene un límite de velocidad predeterminado de 250 000 solicitudes por hora compartido entre /messages/send, /campaigns/trigger/send y /canvas/trigger/send, como se documenta en Límites de velocidad de la API.

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
{
  "campaign_id": (required, string) see campaign identifier,
  "send_id": (optional, string) see send identifier,
  "trigger_properties": (optional, object) personalization key-value pairs that will 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' will only send to users in the audience
  "recipients": (optional, array; if not provided and broadcast is not set to `false`, message will send 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 will apply to this user (these key-value pairs will 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 will 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 will be overwritten
    }
  ],
  "attachments": (optional, array) array of JSON objects that define the files you need attached, defined by "file_name" and "url",
    [
      {  
       "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 will be detected automatically from the URL defined, which should return the appropriate "Content-Type" as a response header. This is required if you use "attachments",
      }
    ]
}

Parámetros de la solicitud

• La matriz de destinatarios puede contener hasta 50 objetos, cada uno de ellos con una única cadena external_user_id y un objeto trigger_properties.
• Cuando send_to_existing_only es true, Braze sólo enviará el mensaje a los usuarios existentes. Sin embargo, esta bandera no puede utilizarse con alias de usuario.
• Cuando send_to_existing_only es false, debe incluirse un atributo. Braze creará un usuario con la dirección id y los atributos antes de enviar el mensaje.

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

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

Detalles de la respuesta

Las respuestas del punto final de envío de mensajes incluirán la dirección dispatch_id del mensaje para que sirva de 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 punto final, 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 la descripción.

Objeto de atribución para campañas

Braze tiene un objeto de mensajería llamado attributes que te permitirá añadir, crear o actualizar atributos y valores de un usuario antes de enviarle una campaña desencadenada por la API. Utilizando el punto final campaign/trigger/send como esta llamada API procesará 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.