Envía mensajes Canvas utilizando la entrega desencadenada por API

Utiliza este punto final para enviar mensajes Canvas con entrega desencadenada por la API.

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

Para poder enviar mensajes con este punto final, debes tener un ID de Canvas (que se crea cuando construyes un Canvas).

Requisitos previos

Para utilizar este punto final, deberás generar una clave de API con el permiso canvas.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
{
  "canvas_id": (required, string) see Canvas identifier,
  "context": (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 Canvas)
    [{
      // 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,
      "canvas_entry_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 `canvas_entry_properties`)
      "send_to_existing_only": (optional, boolean) defaults to true, can't be used with user aliases
      "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
    }],
    ...
}

Parámetros de la solicitud

Es posible que los clientes que utilicen la API para llamadas de servidor a servidor tengan que permitir la URL de API adecuada si están detrás de un cortafuegos.

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
curl --location --request POST 'https://rest.iad-01.braze.com/canvas/trigger/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "canvas_id": "canvas_identifier",
  "canvas_entry_properties": {"product_name" : "shoes", "product_price" : 79.99},
  "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": "user_identifier",
      "send_to_existing_only": true,
      "attributes": {
          "first_name" : "Alex"
      }
    }
  ]
}'

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 (ID único para cada “transmisión” enviada desde la plataforma Braze). Echa un vistazo al comportamiento de Dispatch ID para obtener más información.

Ejemplo de respuesta positiva

El código de estado 201 podría devolver el siguiente cuerpo de respuesta. Si el Canvas está archivado, detenido o en pausa, no se enviará a través de este punto final.

1
2
3
4
5
{
  "notice": "The Canvas is paused. Resume the Canvas to ensure trigger requests will take effect.",
  "dispatch_id": "example_dispatch_id",
  "message": "success"
}

Si tu Canvas está archivado, verás este mensaje notice: “El Canvas” está archivado. Desarchiva el Canvas para asegurarte de que las solicitudes de desencadenamiento surtan efecto”. Si tu Canvas no está activo, verás este mensaje notice: “El Canvas” está en pausa. Reanuda el Canvas para asegurarte de que las peticiones desencadenadas surtan efecto”.

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 Canvas

Utiliza el objeto de mensajería attributes para añadir, crear o actualizar atributos y valores de un usuario antes de enviarle un Canvas desencadenado por la API utilizando el punto final canvas/trigger/send. Esta llamada a la API procesa el objeto de atributos del usuario antes de procesar y enviar el Canvas. Esto ayuda a minimizar el riesgo de problemas causados por condiciones de carrera. Sin embargo, por defecto, los grupos de suscripción no pueden actualizarse de esta forma.