Ad hoc Automation Steps
Ad hoc automations can be defined and invoked in a single API call, without needing to create a full automation template. This document outlines the various types of steps you can use in an ad hoc automation run.
Add to Batch
Add the data object to a batch. Any steps after "add-to-batch" are not executed until the batch conditions are met and the batch is released. The subsequent steps are only invoked once per batch run.
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the add to batch Automation Step, this value should be "add-to-batch" . |
batch_id | string | required | A unique id for the batch. This value must be the same for each event expected to be added to the batch |
wait_period | string | required | Defines the period of inactivity before the batch is released. Specified as an ISO 8601 duration, https://en.wikipedia.org/wiki/ISO_8601#Durations |
max_wait_period | string | required | Defines the maximum wait time before the batch should be released. Must be less than wait period. Maximum of 60 days. Specified as an ISO 8601 duration, https://en.wikipedia.org/wiki/ISO_8601#Durations |
max_items | number | If specified, the batch will release as soon as this number is reached | |
retain | object | required | Defines what items should be retained and passed along to the next steps when the batch is released |
retain.type | string | required | One of first , last , highest , lowest . |
retain.count | number | required | Currently, only 10 is supported |
retain.sort_key | string | Defines the data value data[sort_key] that is used to sort the stored items. Required when type is set to highest or lowest . | |
category_key | string | Defines the field of the data object the batch is set to when complete. Defaults to batch |
Schema
{
"action": "add-to-batch",
"wait_period": "",
"max_wait_period": "",
"max_items": 10,
"retain": {
"type": "first" | "last" | "highest" | "lowest",
"count": 10,
"sort_key": ""
},
"category_key": ""
}
Cancel
Cancel an Automation Run that is In Progress.
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Cancel Automation Step, this value should be "cancel" . |
cancelation_token | string | The string that is associated with the cancelable automation run. An Automation Run is cancelable if it has a cancelation_token value at execution time. | |
if | string | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. | |
ref | string | A pointer to step and its data. |
Schema
{
"action": "cancel",
"cancelation_token": "",
"if": "",
"ref": ""
}
Delay
Wait a duration of time, before proceeding to the next Automation Step.
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Delay Automation Step, this value should be "delay" . |
duration | string | The human readable time duration. A duration value and unit is required, e.g. 5 minutes, 1 hour, 3 days | |
if | string | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. | |
ref | string | A pointer to step and its data. | |
until | string | The ISO 8601 timestamp that describes the length of the delay. |
Either until
or duration
is required.
Schema
{
"action": "delay",
"if": "",
"ref": "",
"until": "",
"duration": ""
}
Fetch Data
Fetch data via https and write the response to the data
property of the Automation Run Cache.
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Fetch Data Automation Step, this value should be "fetch-data" . |
idempotency_expiry | string | A unix epoch timestamp (seconds) or an ISO_8601 date string that describes how long the idempotency_key is valid. | |
idempotency_key | string | A unique value generated by the client which the server uses to recognize subsequent retries of the same request. | |
if | string | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. | |
merge_strategy | enum | replace , soft-merge , overwrite , or none . If nothing is specified then the default strategy is replace . The strategy to merge the webhook response into the Automation Run Cache. Details below. | |
ref | string | A pointer to step and its data. | |
webhook | object | The webhook configuration of the resource that is accessible via http. See the webhook schema bellow. |
The merge_strategy
property can be any of the following values:
replace
- overwrite all properties in the Automation Cache with the http response. Remove's all in properties in the Automation Cache that do not exist in http response.
soft-merge
- only overwrite properties in the Automation Cache with the http response properties that do not yet exist in the Automation Cache.
overwrite
- overwrite all properties in the Automation Cache with the properties from the http response.
none
- do not make any changes to the Automation Cache if the Automation Cache already exists and has data. Otherwise initialize the Automation Cache.
The webhook
can be configured with any of the following properties:
{
"webhook": {
"body": {}, // optional
"headers": {}, // optional
"params": {}, // optional
"method": "GET" | "POST", // optional, default GET
"url": "<API_RESOURCE>"
}
}
Schema
{
"action": "fetch-data",
"idempotency_expiry": "",
"idempotency_key": "",
"if": "",
"merge_strategy": "replace" | "none" | "overwrite" | "soft-merge",
"ref": "",
"webhook": {
"body": {}, // optional
"headers": {}, // optional
"params": {}, // optional
"method": "GET" | "POST", // optional, default GET
"url": "<API_RESOURCE>"
}
}
Invoke
Invoke another Automation Template
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Invoke Automation Step, this value should be "invoke" . |
context | string | The initial values of the Automation Run Cache to invoke the Automation Template with. | |
if | string | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. | |
ref | string | A pointer to step and its data. | |
template | string | required | A unique identifier that can be mapped to an Automation Template. This could be the Template ID or the Alias from the Automation Template Designer. |
Schema
{
"action": "invoke",
"context": {
"brand": "",
"data": {},
"profile": {},
"template": "",
"recipient": ""
},
"if": "",
"ref": "",
"template": ""
}
Send (Legacy)
Send a Notification Template
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Send Automation Step, this value should be "send" . |
recipient | string | required | A unique identifier associated with the recipient of the delivered message. |
template | string | required | A unique identifier that can be mapped to an individual Notification. This could be the "Notification ID” on Notification detail pages (see the Notifications page in the Courier app) or a custom string mapped to the event in settings. |
brand | string | The brand id to be used in the notification. | |
data | string | An object that includes any data you want to pass to a message template. The data will populate the corresponding template variables. | |
if | string | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. | |
idempotency_expiry | string | A unix epoch timestamp (seconds) or an ISO_8601 date string that describes how long the idempotency_key is valid. | |
idempotency_key | string | A unique value generated by the client which the server uses to recognize subsequent retries of the same request. | |
override | string | An object that is merged into the request sent by Courier to the provider to override properties or to gain access to features in the provider API that are not natively supported by Courier. | |
profile | string | An object that includes any key-value pairs required by your chosen Integrations (see our Provider Documentation for the requirements for each Integration.) If profile information is included in the request and that information already exists in the profile for the recipientId, that information will be merged. | |
ref | string | A pointer to step and its data. |
Schema
{
"action": "send",
"brand": "",
"data": {},
"if": "",
"idempotency_expiry": "",
"idempotency_key": "",
"override": {},
"profile": {},
"recipient": "",
"ref": ""
}
Send
Send a Notification Template
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Send Automation Step, this value should be "send" . |
message | object | required | The Courier Message. For more information see The Courier Message in the /send api reference. |
Schema
{
"action": "send",
"message": {
"to": {
// profile
},
// either template or content is required but not both
"template": "",
"content": {}
}
}
Send List
Send a message to each recipient in the list. Optionally fetch data for each recipient via http and merge the response into the data
property of the Automation Run Cache.
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Send List Automation Step, this value should be "send-list" . |
brand | string | The brand id to be used in the notification. | |
data | string | An object that includes any data you want to pass to a message template. The data will populate the corresponding template variables. | |
data_source | object | The webhook configuration of the resource that is accessible via http. See the data_source schema bellow. | |
idempotency_expiry | string | A unix epoch timestamp (seconds) or an ISO_8601 date string that describes how long the idempotency_key is valid. | |
idempotency_key | string | A unique value generated by the client which the server uses to recognize subsequent retries of the same request. | |
if | string | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. | |
list | string | required | The Courier List Id. |
override | string | An object sent by Courier to the provider to leverage features of the provider API or to simply override properties of the provider api call. | |
template | string | required | A unique identifier that can be mapped to an individual Notification. This could be the "Notification ID” on Notification detail pages (see the Notifications page in the Courier app) or a custom string mapped to the event in settings. |
ref | string | A pointer to step and its data. |
The merge_strategy
property of the steps data_source
object, can be any of the following values:
replace
- overwrite all properties in the Automation Cache with the http response. Remove's all in properties in the Automation Cache that do not exist in http response.
soft-merge
- only overwrite properties in the Automation Cache with the http response properties that do not yet exist in the Automation Cache.
overwrite
- overwrite all properties in the Automation Cache with the properties from the http response.
none
- do not make any changes to the Automation Cache if the Automation Cache already exists and has data. Otherwise initialize the Automation Cache.
The webhook
property of the steps data_source
object, can be configured with any of the following properties:
{
"webhook": {
"body": {}, // optional
"headers": {}, // optional
"params": {}, // optional
"method": "GET" | "POST", // optional, default GET
"url": "<API_RESOURCE>"
}
}
Schema
{
"action": "send-list",
"brand": "",
"data": {},
"data_source": {
"webhook": {
"url": "WEBHOOK_URL",
"method": "GET",
"headers": {}
},
"merge_strategy": "replace"
},
"idempotency_expiry": "",
"idempotency_key": "",
"if": "",
"list": "",
"override": {},
"ref": "",
"template": ""
}
Update Profile
Update the Courier Profile given a recipientId.
Fields
Field | Type | Required | Description |
---|---|---|---|
action | string | required | The type of element. For the Update Profile Automation Step, this value should be "update-profile" . |
if | string | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. | |
merge | enum | replace , soft-merge , overwrite , or none . If nothing is specified then the default strategy is replace . The strategy to merge new data into the recipient profile. Details below. | |
profile | string | An object that includes any key-value pairs associated with the recipient profile | |
recipient_id | string | A unique identifier associated with the recipient profile you intend to update. | |
ref | string | A pointer to step and its data. |
The merge
property can be any of the following values:
replace
- overwrite all properties in the recipient profile with the http response. Remove's all in properties in the recipient profile that do not exist in http response.
soft-merge
- only overwrite properties in the recipient profile with the http response properties that do not yet exist in the recipient profile.
overwrite
- overwrite all properties in the recipient profile with the properties from the http response.
none
- do not make any changes to the recipient profile if the recipient profile already exists and has data. Otherwise initialize the recipient profile
When using update-profile steps, be mindful with the aforementioned merge strategies that can update an existing profile that was created with a Segment Identify event.
Schema
{
"action": "update-profile",
"if": "",
"merge": "replace",
"profile": {},
"recipient_id": "",
"ref": ""
}