Loading...
Skip to main content

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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the add to batch Automation Step, this value should be "add-to-batch".
batch_idstringrequiredA unique id for the batch. This value must be the same for each event expected to be added to the batch
wait_periodstringrequiredDefines 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_periodstringrequiredDefines 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_itemsnumberIf specified, the batch will release as soon as this number is reached
retainobjectrequiredDefines what items should be retained and passed along to the next steps when the batch is released
retain.typestringrequiredOne of first, last, highest, lowest.
retain.countnumberrequiredCurrently, only 10 is supported
retain.sort_keystringDefines the data value data[sort_key] that is used to sort the stored items. Required when type is set to highest or lowest.
category_keystringDefines 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Cancel Automation Step, this value should be "cancel".
cancelation_tokenstringThe string that is associated with the cancelable automation run. An Automation Run is cancelable if it has a cancelation_token value at execution time.
ifstringA boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data.
refstringA 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Delay Automation Step, this value should be "delay".
durationstringThe human readable time duration. A duration value and unit is required, e.g. 5 minutes, 1 hour, 3 days
ifstringA boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data.
refstringA pointer to step and its data.
untilstringThe 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Fetch Data Automation Step, this value should be "fetch-data".
idempotency_expirystringA unix epoch timestamp (seconds) or an ISO_8601 date string that describes how long the idempotency_key is valid.
idempotency_keystringA unique value generated by the client which the server uses to recognize subsequent retries of the same request.
ifstringA boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data.
merge_strategyenumreplace, 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.
refstringA pointer to step and its data.
webhookobjectThe 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Invoke Automation Step, this value should be "invoke".
contextstringThe initial values of the Automation Run Cache to invoke the Automation Template with.
ifstringA boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data.
refstringA pointer to step and its data.
templatestringrequiredA 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Send Automation Step, this value should be "send".
recipientstringrequiredA unique identifier associated with the recipient of the delivered message.
templatestringrequiredA 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.
brandstringThe brand id to be used in the notification.
datastringAn object that includes any data you want to pass to a message template. The data will populate the corresponding template variables.
ifstringA boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data.
idempotency_expirystringA unix epoch timestamp (seconds) or an ISO_8601 date string that describes how long the idempotency_key is valid.
idempotency_keystringA unique value generated by the client which the server uses to recognize subsequent retries of the same request.
overridestringAn 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.
profilestringAn 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.
refstringA 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Send Automation Step, this value should be "send".
messageobjectrequiredThe 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Send List Automation Step, this value should be "send-list".
brandstringThe brand id to be used in the notification.
datastringAn object that includes any data you want to pass to a message template. The data will populate the corresponding template variables.
data_sourceobjectThe webhook configuration of the resource that is accessible via http. See the data_source schema bellow.
idempotency_expirystringA unix epoch timestamp (seconds) or an ISO_8601 date string that describes how long the idempotency_key is valid.
idempotency_keystringA unique value generated by the client which the server uses to recognize subsequent retries of the same request.
ifstringA boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data.
liststringrequiredThe Courier List Id.
overridestringAn object sent by Courier to the provider to leverage features of the provider API or to simply override properties of the provider api call.
templatestringrequiredA 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.
refstringA 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

FieldTypeRequiredDescription
actionstringrequiredThe type of element. For the Update Profile Automation Step, this value should be "update-profile".
ifstringA boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data.
mergeenumreplace, 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.
profilestringAn object that includes any key-value pairs associated with the recipient profile
recipient_idstringA unique identifier associated with the recipient profile you intend to update.
refstringA 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
Profile Merging

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": ""
}