Learn how to trigger workflows using direct workflow API, with code snippets and examples.
"$skip_create": true
flag.This can be applied inside the actor, individual user recipient objects, or object recipient objects.Property | Type | Description |
---|---|---|
workflow | string | Slug of the designed workflow on the SuprSend dashboard. You’ll get the slug from workflow settings. |
actor (optional) | string / object | Includes distinct_id and properties of the user who performed the action. Used for cross-user notifications, where you need to include actor properties in the notification template. Actor properties can be added as $actor.<prop> . |
recipients | array of string / array of objects | List of users who need to be notified. You can add up to 100 recipients in a workflow trigger. Recipients can be passed as an array of distinct_ID (if the user is pre-synced in the SuprSend database) or defined inline. |
data | object | Variable data required to render dynamic template content or workflow properties such as dynamic delay or channel override in the send node. |
tenant_id | string | Unique identifier of the brand / tenant. |
idempotency_key | string | Unique identifier of the request. It will be returned in the outbound webhook response. You can use it to map notification statuses and replies in your system. |
recipients[].$timezone | string | Used to set the recipient’s timezone. Allows sending notifications in the user’s local timezone. Pass the timezone in IANA (TZ identifier) format. |
recipients[].$preferred_language | string | Used to set the recipient’s preferred language. |
distinct_ids
or recipient objects. You can pass up to 100 recipients in a single workflow trigger. SuprSend will internally convert it into multiple workflow triggers, one for each recipient in the array.
$recipient.<property>
.
This is how the complete recipient object with look like
Property | Type | Description |
---|---|---|
distinct_id | string | Unique identifier of the user to be notified. |
$<channel> (e.g. $sms ) | array of string / objects | You can pass user channel information using $<channel> key. The channel info will be updated in the user profile in the background. For this workflow, only channel values specified in this key will be used for sending notifications (instead of all channel values present in the user profile). Refer to how different communication channels can be passed here. |
$channels | array of string | Use it to pass the user’s channel preference in the payload. You can always use our in-built preference APIs to maintain user notification preferences. Preferences defined within SuprSend will automatically apply with the workflow trigger. By default, notifications will be sent to all channels defined in the workflow delivery node. However, if the user has a specific channel preference for a notification (e.g. only wants to receive payment reminders via email), you can include that preference in the workflow payload. This ensures notifications are sent only to the channels specified in the $channels key. Supported channel values: email, sms, whatsapp, androidpush, iospush, slack, webpush, ms_teams . |
$preferred_language | string | To set the recipient’s preferred language. This supports localization in notification content. Pass the language in ISO 639-1 2-letter format. Refer to all language codes here. |
$timezone | string | To set the recipient’s timezone. Used to send notifications in the user’s local timezone. Pass the timezone in IANA (TZ identifier) format. |
* | key-value pair | You can pass other user properties to render dynamic template content in key-value pairs like "user_prop1": "value1" . Extra properties will be set in the subscriber profile (as subscriber properties), which can then be used in the template as $recipient.<property> . |
$actor.<property>
.
Sample template with actor and recipient properties:
"is_transient": True
in your recipient object. This approach is recommended for scenarios where you need to send notifications to unregistered users without creating them in the SuprSend platform. The same way, you can pass "is_transient": True
in your actor object to use actor properties in template without creating user profile.
tenant_id
in your workflow instance. You can use this to dynamically manage tenant level notification customizations. This includes the ability to customize template design or content and route notifications via tenant vendors.
idempotency_key
for next 24 hours. Idempotency key should be uniquely generated for each request (max 255 characters allowed). Spaces in start and end of the key will be trimmed. Here are some common approaches for generating idempotency keys:
user147-new-comment-1687437670
.append()
on workflows.bulk_trigger_instance()
instance to add however-many-records to call in bulk.
wf_instance.add_attachment()
for each file with local-path. Ensure that file_path is proper, otherwise it will raise FileNotFoundError.
supr_client.trigger_workflow
method.
The SDK internally makes an HTTP
call to SuprSend Platform to register this request, and you’ll immediately receive a response indicating the acceptance status. Note: The actual processing/execution of workflow happens asynchronously.
Once your request is accepted, you can check the status of your request in the ’ SuprSend Logs’ section.
Parameter | Description | Format | Obligation |
---|---|---|---|
name | It is the unique name of the workflow. You can see workflow-related analytics on the workflow page (how many notifications were sent, delivered, clicked, or interacted). The workflow name should be easily identifiable for your reference at a later stage. | text | Mandatory |
template | It is the unique slug of the template created on the SuprSend platform. You can get this slug by clicking on the clipboard icon next to the Template name on the SuprSend templates page. It is the same for all channels. | slug name | Mandatory |
notification_category | You can understand more about them in the Notification Category documentation. | system / transactional / promotional | Mandatory |
delay | Workflow will be halted for the time mentioned in delay and becomes active once the delay period is over. | **XX**d**XX**h**XX**m**XX**s or if it’s a number (n ), then delay is in seconds (n ). | Optional |
trigger_at | Trigger workflow on a specific date-time. | Date string in ISO 8601 format e.g. "2021-08-27T20:14:51.643Z" | Optional |
users | Array object of target users. At least 1 user mandatory.distinct_id for each user is mandatory. You can pass up to 100 entries in the users array. Channel information is non-mandatory. If you pass channel information here, then these channels will be used for sending notifications; otherwise, channels will be picked from the user profile. | json"users": [ { "distinct_id": "value", "$channels": [], channel_information_dict #(optional) } ] | Mandatory |
delivery | Delivery instructions for the workflow. You can enable smart delivery by setting "smart": True .By default, the delivery instruction will be:json"delivery": { "smart": False, "success": "seen" } Further details are given in the below section. | json"delivery": { "smart": True/False, "success": "delivered/seen/interaction/<some-user-defined-success-event>", "time_to_live": "<TTL duration>", "mandatory_channels": [] } | Optional |
data | JSON. To replace variables in the template, templates use the handlebars language. | json "data": { "key": { "key": "value", "key": "value" } } | Optional |
brand_id | Brand_id of the tenant to trigger a notification on behalf of your tenants. | string | Optional |
idempotency_key | Unique key in the request call for idempotent requests. | string | Optional |
$sms
and $whatsapp
, +<countrycode>
is mandatory to send along with phone number. Eg: +1 for USTo find the template slug name on SuprSend platform, click on the clipboard icon on Templates page. Templates > Template Details Page
.append()
on bulk_workflows
instance to add however-many-records to call in bulk.