Zeitplan für API-getriggerte Canvases
Verwenden Sie diesen Endpunkt, um Canvas-Nachrichten über eine API-getriggerte Zustellung zu planen. Dabei können Sie festlegen, welche Aktion den Versand der Nachricht triggern soll.
Sie können context übergeben, das als Template in die Nachrichten eingefügt wird, die von den ersten Schritten des Canvas gesendet werden.
Die Terminologie und der Liquid-Namespace, die Sie sehen, hängen von den in Ihrem Workspace verfügbaren Features ab:
- Wenn das Dashboard Kontextvariablen anzeigt, referenzieren Sie Entry-Eigenschaften mit
context, z. B.{{context.${property_name}}}. Sie können Variablen auch mit einem Kontext-Schritt erstellen oder aktualisieren. - Wenn das Dashboard Canvas-Entry-Eigenschaften anzeigt, referenzieren Sie diese mit
canvas_entry_properties, z. B.{{canvas_entry_properties.${property_name}}}. Der Kontext-Schritt und der Filter Kontextvariable sind nicht verfügbar.
Weitere Informationen finden Sie unter Kontext und Kontext- und Event-Eigenschaften. Wenn Sie Zugriff auf Canvas-Kontext benötigen, wenden Sie sich an Ihren Customer-Success-Manager.
Beachten Sie, dass Sie zum Versenden von Nachrichten über diesen Endpunkt eine Canvas-ID benötigen, die beim Erstellen eines Canvas generiert wird.
Canvas-Eintritte werden zum geplanten Nachrichtenversandzeitpunkt erfasst, nicht zum Zeitpunkt dieser API-Anfrage. Nutzer:innen, die für einen zukünftigen Zeitplan getriggert werden, erscheinen erst als Eintritte, wenn der geplante Zeitpunkt erreicht ist.
Voraussetzungen
Um diesen Endpunkt zu verwenden, benötigen Sie einen API-Schlüssel mit der Berechtigung canvas.trigger.schedule.create.
Rate-Limit
Wenn Sie in Ihrer Anfrage Connected-Audience-Filter verwenden, gilt für diesen Endpunkt ein Rate-Limit von 250 Anfragen pro Minute. Wenn Sie stattdessen eine external_id angeben, gilt für diesen Endpunkt ein Standard-Rate-Limit von 250.000 Anfragen pro Stunde, das zwischen den in API-Rate-Limits dokumentierten Endpunkten geteilt wird.
Dieser Endpunkt unterstützt die Stapelverarbeitung von API-Anfragen. Eine einzelne Anfrage kann Folgendes enthalten:
- Standardmäßig bis zu 50
recipients - Eine Connected Audience beliebiger Größe
Anfragetext
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
"canvas_id": (required, string) see Canvas identifier,
// Including 'recipients' will send only to the provided user ids if they are in the campaign's segment
"recipients": (optional, array of recipients object),
// for any keys that conflict between these trigger properties and those in a Recipients Object, the value from the
// Recipients Object will be used
"audience": (optional, connected audience object) see connected audience,
// Including 'audience' will only send to users in the audience
// If 'recipients' and 'audience' are not provided and broadcast is not set to 'false',
// the message will send to entire segment targeted by the Canvas
"broadcast": (optional, boolean) see broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" object is omitted,
"context": (optional, object) personalization key-value pairs for the first step for all users in this send; see trigger properties,
"schedule": {
"time": (required, datetime as ISO 8601 string) time to send the message,
"in_local_time": (optional, bool),
"at_optimal_time": (optional, bool),
}
}
Anfrageparameter
| Parameter | Erforderlich | Datentyp | Beschreibung |
|---|---|---|---|
canvas_id |
Erforderlich | String | Siehe Canvas-Bezeichner. |
recipients |
Optional | Array von Empfänger:innen-Objekten | Siehe Empfänger:innen-Objekt. |
audience |
Optional | Verbundenes Zielgruppen-Objekt | Siehe verbundene Zielgruppe. |
broadcast |
Optional | Boolescher Wert | Sie müssen broadcast auf true setzen, wenn Sie eine Nachricht an ein ganzes Segment senden, auf das eine Campaign oder ein Canvas abzielt. Dieser Parameter ist standardmäßig auf false eingestellt (Stand: 31. August 2017). Wenn broadcast auf true gesetzt ist, kann keine recipients-Liste angegeben werden. Seien Sie jedoch vorsichtig, wenn Sie broadcast: true setzen, denn wenn Sie dieses Flag unbeabsichtigt setzen, kann dies dazu führen, dass Ihre Nachricht an eine größere Zielgruppe als erwartet gesendet wird. |
context |
Optional | Objekt | Schlüssel-Wert-Paare zur Personalisierung für alle Nutzer:innen in dieser Sendung. Siehe Canvas-Kontext-Objekt. |
schedule |
Erforderlich | Zeitplan-Objekt | Siehe Zeitplan-Objekt. |
Beispielanfrage
curl --location --request POST 'https://rest.iad-01.braze.com/canvas/trigger/schedule/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"canvas_id": "canvas_identifier",
"recipients": [
{
"user_alias": "example_alias",
"external_user_id": "external_user_identifier",
"context": {}
}
],
"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"
}
}
]
},
"broadcast": false,
"context": {},
"schedule": {
"time": "",
"in_local_time": false,
"at_optimal_time": false
}
}'
Antwort
Beispiel für eine erfolgreiche Antwort
Content-Type: application/json
Authorization: Bearer YOUR-API-KEY-HERE
{
{
"dispatch_id": "dispatch_identifier",
"schedule_id": "schedule_identifier",
"message": "success"
}