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 designed workflow on 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. You can use it for cross-user notifications where you need to include actor properties in notification template. Actor properties can be added as $actor.<prop> . |
recipients | array of string / array of objects | List of users or objects who need to be notified. You can add up to 100 recipients in a workflow trigger. You can either pass recipients as an array of distinct_ID (if user is pre-synced in SuprSend database) or define recipient information inline. |
data | object | variable data required to render dynamic template content or workflow properties such as dynamic delay or channel override in send node. |
tenant_id | string | unique identifier of the brand / tenant |
idempotency_key | string | unique identifier of the request. We’ll be returning idempotency_key in our outbound webhook response. You can use it to map notification statuses and replies in your system. |
recipients[].$timezone | string | to set recipient’s timezone. Used to send notification in user’s local timezone. You can pass timezone in IANA (TZ identifier) format. |
recipients[].$preferred_language | string | to set recipient’s preferred language. This is to support localization in notification content. You can pass the language in ISO 639-1 2-letter format. Refer all language codes here . |
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> like $email , $sms etc. | array of string / objects | You can pass user channel information using $<channel> key. The channel info will be updated to user profile in the background. For this workflow, only channel values specified in this key will be used for sending notification (instead of all channel values present in User profile). Refer how different communication channels can be passed here |
$channels | array of string | Use it to pass user’s channel preference in the payload. You can always use our in-build preference APIs to maintain user notification preferences. Preferences defined within SuprSend will automatically apply with workflow trigger. By default, notifications will be sent to all channels defined in the workflow delivery node. However, if you have a scenario where user has specific channel preference for a notification (e.g. they only want to receive payment reminders via email), you can include that preference in the workflow payload. This will ensure that notifications are sent only to the channels specified in the $channels key. The supported channel values are email, sms, whatsapp, androidpush, iospush, slack, webpush, ms_teams . |
$preferred_language | string | to set recipient’s preferred language. This is to support localization in notification content. You can pass the language in ISO 639-1 2-letter format. Refer all language codes here . |
$timezone | string | to set recipient’s timezone. Used to send notification in user’s local timezone. You can pass timezone in IANA (TZ identifier) format. |
* | key-value pair | You can pass other user properties to render dynamic template content in key-value pair as "user_prop1":"value1" . Extra properties will be set in 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.bulkTriggerInstance()
instance to add however-many-records to call in bulk.
Response is an instance of suprsend.BulkResponse
type.
wfInstance.AddAttachment()
for each file with local-path or an accessible URL.
$sms
and $whatsapp
, +<countrycode>
is mandatory to send along with phone number. Eg: +1 for USParameter | 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 SuprSend platform. You can get this slug by clicking on the clipboard icon next to the Template name on SuprSend templates page. It is the same for all channels | 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 become active once the delay period is over. | XXdXXhXXmXXs or if its number (n) then delay is in seconds (n) | Optional |
users | Array object of target users. At least 1 user mandatory. distinct_id for each user mandatory Channel information is non-mandatory. If you pass channel information here, then these channels will be used for sending notification otherwise channels will be picked from user profile. | "users": { "distinct_id": "value", "$channels": [], "channel_information_dict": {} }, | Mandatory |
delivery | Delivery instructions for the workflow. You can enable smart delivery by setting "smart":True By default, delivery instruction will be "delivery": { "smart": False, "success": "seen" } Further details are given in the below section | delivery = { "smart": True/False, "success": "delivered/seen/interaction/", "time_to_live": "", "mandatory_channels": [] } # list of mandatory channels e.g gation”, | Optional |
data | JSON. To replace the variables in the template, templates use handlebars language | "data": { "key": { "key": "value", "key": "value" } }, | Optional |
To find the template slug name on SuprSend platform, click on the clipboard icon on Templates page. Templates > Template Details Page
suprClient.TriggerWorkflow
, the SDK internally makes an HTTP
call to SuprSend Platform to register this request, and you’ll get an error message if something fails
name
.
.Append()
on BulkWorkflows
instance to add however-many-records to call in bulk.
Response is an instance of suprsend.BulkResponse
type