> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Trigger Workflow from API
> Learn how to trigger workflows using direct workflow API, with code snippets and examples.
It is a unified API to trigger workflow and doesn't require user creation before hand to trigger notification. Recommended for platforms transitioning their existing notifications to SuprSend. If you are using our frontend SDKs to configure notifications and passing events and user properties from third-party data platforms like Segment, then [event-based trigger](/docs/go-send-event-data) would be a better choice.
Available in SDK version >= v0.5.1
## Payload Schema
```go Sample Payload theme={"system"}
package main
import (
"log"
suprsend "github.com/suprsend/suprsend-go"
)
// Initialize SDK
func main() {
suprClient, err: = suprsend.NewClient("_workspace_key_", "_workspace_secret_")
if err != nil {
log.Println(err)
}
_ = suprClient
triggerWorkflowAPI(suprClient)
}
func triggerWorkflowAPI(suprClient * suprsend.Client) {
// Create WorkflowRequest body
wfReqBody: = map[string] interface {} {
"workflow": "_workflow_slug_",
"actor": map[string] interface {} {
"distinct_id": "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08",
"name": "actor_1",
"$skip_create": true,
},
"recipients": [] map[string] interface {} {
// notify user
{
"distinct_id": "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
"$email": [] string {
"abc@example.com"
},
"name": "recipient_1",
"$preferred_language": "en",
"$timezone": "America/New_York",
"$skip_create": true,
},
// notify object
{
"object_type": "teams",
"id": "finance",
"$skip_create": true,
},
},
// data can be any json/serializable map structure
"data": map[string] interface {} {
"first_name": "User",
"invoice_amount": "$5000",
"invoice_id": "Invoice-1234",
"spend_amount": "$10",
},
}
w1: = & suprsend.WorkflowTriggerRequest {
Body: wfReqBody,
TenantId: "tenant_id1",
IdempotencyKey: "_unique_identifier_of_the_request_",
}
// Call Workflows.Trigger to send request to Suprsend
resp,
err: = suprClient.Workflows.Trigger(w1)
if err != nil {
log.Fatalln(err)
}
log.Println(resp)
}
```
```go Response theme={"system"}
{
"success": true, // if true, request was accepted.
"status": "success",
"status_code": 202, // http status code
"message": "OK",
}
```
To prevent automatic creation of an actor, or recipient (user/object) in SuprSend (the case where they already exist in your system), you can use the `"$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](/docs/go-trigger-workflow-from-api#sending-cross-user-notifications) where you need to include actor properties in notification template. Actor properties can be added as `$actor.`. |
| 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](/docs/go-trigger-workflow-from-api#identifying-recipients-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](/docs/tenants) |
| idempotency\_key | string | unique identifier of the request. We'll be returning idempotency\_key in our [outbound webhook response](/docs/outbound-webhook). 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)](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) 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](https://github.com/suprsend/suprsend-py-sdk/blob/v0.12.0/src/suprsend/language_codes.py) . |
### Sending notification to multiple recipients
Recipients in workflow call is an array of `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.
```go Request theme={"system"}
"recipients": []map[string]interface{}{
{
"distinct_id": "id1",
"$email":["abc@example.com"],
"name":"recipient_1"
},
{
"distinct_id": "id1",
"$email":["abc@example.com"],
"name":"recipient_2"
}
}
---- OR ------
"recipients": []string{"id1","id2"}
```
**Use lists to broadcast to a large list of users:**
We recommend you to use [lists](/docs/lists) and [broadcasts](/docs/broadcast) to send notifications to a user list larger than 1000 users. This approach allows for bulk processing within SuprSend, resulting in significantly faster delivery compared to individual workflow calls. Sending individual workflows to a large set of users may introduce delays in your notification queue and is not an optimized way of handling bulk trigger.
### Identifying recipients inline
One of the benefits of using direct workflow trigger is that you can identify recipients inline. You can include recipient channel information, their channel preferences, and their user properties along with the workflow trigger. Upon triggering the workflow, the recipient will be automatically created in the SuprSend database in the background. This facilitates dynamic synchronization of your user data within SuprSend and eliminates the need for any migration efforts on your end to start sending notifications from SuprSend. You can also use recipient properties in your template as `$recipient.`.
This is how the complete recipient object with look like
```json Request theme={"system"}
"recipients": []map[string]interface{}{
{
"distinct_id": "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
"$email":["abc@example.com"],
"$channels":["email","inbox"],
"user_prop1":"value_1",
"$preferred_language":"en",
"$timezone": "America/New_York"
}
}
```
| Property | Type | Description |
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| distinct\_id | string | Unique identifier of the user to be notified. |
| `$` like `$email`, `$sms` etc. | array of string / objects | You can pass user channel information using `$` 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](/docs/go-trigger-workflow-from-api#add-user-communication-channel) |
| \$channels | array of string | Use it to pass user's channel preference in the payload. You can always use our [in-build preference APIs](/docs/user-preferences) 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](https://github.com/suprsend/suprsend-py-sdk/blob/v0.12.0/src/suprsend/language_codes.py) . |
| \$timezone | string | to set recipient's timezone. Used to send notification in user's local timezone. You can pass timezone in [IANA (TZ identifier)](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) 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.`. |
#### Add user communication channel
You can add channels in recipient map as shown below:
```go Request theme={"system"}
"$email":["abc@example.com"],
"$whatsapp":["+15555555555"],
"$sms":["+15555555555"],
"$androidpush": map[string]interface{}{"token": "__android_push_token__", "provider": "fcm"},
"$iospush":map[string]interface{}{{"token": "__ios_push_token__", "provider": "apns"},
"$slack": map[string]interface{}{
"email": "abc@example.com",
"access_token": "xoxb-XXXXXXXX"
} // slack using email
"$slack": map[string]interface{}{
"user_id": "U/WXXXXXXXX",
"access_token": "xoxb-XXXXXX"
} // slack using member_id
"$slack": map[string]interface{}{
"channel": "CXXXXXXXX",
"access_token": "xoxb-XXXXXX"
} // slack channel
"$slack": map[string]interface{}{
"incoming_webhook": {
"url": "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
}
} // slack incoming webhook
"$ms_teams": map[string]interface{}{
"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
"service_url": "https://smba.trafficmanager.net/amer",
"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
} // MS teams user or channel using conversation_id
"$ms_teams": map[string]interface{}{
"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
"service_url": "https://smba.trafficmanager.net/amer",
"user_id": "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
} // MS teams user using user_id
"$ms_teams": map[string]interface{}{
"incoming_webhook": {
"url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
}
} // MS teams incoming webhook
```
### Sending cross-user notifications
In scenarios where you need to notify a group of users based on another user's action, such as sending a notification to the document owner when someone comments on it, you can specify the actor in your workflow call. This allows you to use actor's name or other properties in your notification template. Actor properties can be included in the template as `$actor.`.
Sample template with actor and recipient properties:
```text text theme={"system"}
//handlebar template
Hi {{$recipient.name}}, {{$actor.name}} added {{length comments}} new comments on the {{doc_name}}.
//Rendered content
Hi recipient_1, actor_1 added 2 new comments on the annual IT report.
```
```go Sample workflow body theme={"system"}
wfReqBody := map[string]interface{}{
"workflow": "new_comment",
"actor": map[string]interface{}{
"distinct_id": "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08",
"name": "actor_1",
},
"recipients": []map[string]interface{}{
{
"distinct_id": "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
"$email": []string{"abc@example.com"},
"name":"recipient_1"
},
},
// # data can be any json / serializable python-dictionary
"data": map[string]interface{}{
"doc_name": "annual IT report",
"date": "2024-01-01",
"comments":["change the date","rest looks good"],
},
}
```
### Sending notification to anonymous user
You can send notifications to anonymous users by passing ` "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.
```go Request theme={"system"}
package main
import (
"log"
suprsend "github.com/suprsend/suprsend-go"
)
// Initialize SDK
func main() {
suprClient, err := suprsend.NewClient("_workspace_key_", "_workspace_key_")
if err != nil {
log.Println(err)
}
_ = suprClient
triggerWorkflowAPI(suprClient)
}
func triggerWorkflowAPI(suprClient *suprsend.Client) {
// Create WorkflowRequest body
wfReqBody := map[string]interface{}{
"workflow": "_workflow_slug_",
"actor": map[string]interface{}{
"is_transient": true,
"name": "actor_1",
},
"recipients": []map[string]interface{}{
{
"is_transient": true,
"$email": []string{"abc@example.com"},
"name":"recipient_1",
},
},
// # data can be any json / serializable python-dictionary
"data": map[string]interface{}{
"first_name": "User",
"invoice_amount": "$5000",
"invoice_id":"Invoice-1234",
"spend_amount": "$10",
},
}
w1 := &suprsend.WorkflowTriggerRequest{
Body: wfReqBody,
TenantId: "tenant_id1",
IdempotencyKey: "_unique_identifier_of_the_request_",
}
// Call Workflows.Trigger to send request to Suprsend
resp, err := suprClient.Workflows.Trigger(w1)
if err != nil {
log.Fatalln(err)
}
log.Println(resp)
}
```
### Multi-tenant notifications
For use cases where you want to send notifications to your enterprise customers' end users, pass the `tenant_id` in your workflow instance. You can use this to dynamically manage [tenant level notification customizations](/docs/tenants). This includes the ability to customize template design or content and route notifications via tenant vendors.
```go Request theme={"system"}
package main
import (
"log"
suprsend "github.com/suprsend/suprsend-go"
)
// Initialize SDK
func main() {
suprClient, err := suprsend.NewClient("_workspace_key_", "_workspace_key_")
if err != nil {
log.Println(err)
}
_ = suprClient
triggerWorkflowAPI(suprClient)
}
func triggerWorkflowAPI(suprClient *suprsend.Client) {
// Create WorkflowRequest body
wfReqBody := map[string]interface{}{...}
w1 := &suprsend.WorkflowTriggerRequest{
Body: wfReqBody,
TenantId: "tenant_id1",
IdempotencyKey: "_unique_identifier_of_the_request_",
}
// Call Workflows.Trigger to send request to Suprsend
resp, err := suprClient.Workflows.Trigger(w1)
if err != nil {
log.Fatalln(err)
}
log.Println(resp)
}
```
```go Response theme={"system"}
{
success: true,
status: "success",
status_code: 202,
message: { status: "success" }
}
```
### Idempotent requests
SuprSend supports idempotency to ensure that requests can be retried safely without duplicate processing. If Suprsend receives and processes a request with an idempotency\_key, it will skip processing requests with same `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:
* **Generate a random UUID**for each request.
* **Construct the idempotency key by combining relevant information about the request**. This can include parameters, identifiers, or specific contextual details that are meaningful within your application. e.g., you could concatenate the user ID, action, and timestamp to form an idempotency key like`user147-new-comment-1687437670`
* **Request-specific Identifier**: If your request already contains a unique identifier, such as an order ID or a job ID, you can use that identifier directly as the idempotency key.
Once your request is accepted, you can check the status of your request in the '[ SuprSend Logs](https://app.suprsend.com/en/staging/logs)' section.
## Bulk API for triggering multiple workflows
Bulk API allows you to send multiple workflow requests in a single call. There isn't any limit on number-of-records that can be added to bulk\_workflows instance. Use `.Append()` on `Workflows.bulkTriggerInstance()` instance to add however-many-records to call in bulk.
Response is an instance of `suprsend.BulkResponse` type.
```go Request theme={"system"}
package main
import (
"log"
suprsend "github.com/suprsend/suprsend-go"
)
// Initialize SDK
func main() {
suprClient, err := suprsend.NewClient("_workspace_key_", "_workspace_key_")
if err != nil {
log.Println(err)
}
_ = suprClient
triggerWorkflowAPI(suprClient)
}
func triggerWorkflowAPI(suprClient *suprsend.Client) {
// Create WorkflowRequest body
wfReqBody1 := map[string]interface{}{...}
wfReqBody2 := map[string]interface{}{...}
// Workflow: 1
w1 := &suprsend.WorkflowTriggerRequest{
Body: wfReqBody1,
TenantId: "tenant_id1",
IdempotencyKey: "_unique_identifier_of_the_request_",
}
// Workflow: 2
w2 := &suprsend.WorkflowTriggerRequest{
Body: wfReqBody2,
TenantId: "tenant_id1",
IdempotencyKey: "_unique_identifier_of_the_request_",
}
// ...... Add as many Workflow records as required.
// Create bulk workflows instance
bulkIns := suprClient.Workflows.bulkTriggerInstance()
// add all your workflows to bulkInstance
bulkIns.Append(w1, w2)
// Trigger
bulkResponse, err := bulkIns.Trigger()
if err != nil {
log.Println(err)
}
log.Println(bulkResponse)
}
```
```go Response theme={"system"}
// Response structure
suprsend.BulkResponse{
Status : "success",
Total : 10, // number of records sent in bulk
Success : 10, // number of records succeeded
Failure : 0, // number of records failed
Warnings: [],
FailedRecords : [],
}
suprsend.BulkResponse{
Status : "fail",
Total : 10, // number of records sent in bulk
Success : 0, // number of records succeeded
Failure : 10, // number of records failed
Warnings: []
FailedRecords : [{"record": {...}, "error": "error_str", "code": 500}]
}
suprsend.BulkResponse{
Status : "partial",
Total : 10, // number of records sent in bulk
Success : 6, // number of records succeeded
Failure : 4, // number of records failed
Warnings: []
FailedRecords : [{"record": {...}, "error": "error_str", "code": 500}]
}
```
## Add file attachment in email
To add one or more Attachments to a Notification (viz. Email), call `wfInstance.AddAttachment()` for each file with local-path or an accessible URL.
```go Request theme={"system"}
workflowBody := {...}
wfInstance := Workflow{Body: workflowBody}
// this snippet can be used to add attachment to workflow
err = wfInstance.AddAttachment("https://file_path.pdf")
if err != nil {
log.Println(err)
}
```
A single workflow body size (including local file attachment) must not exceed 800KB (800 x 1024 bytes). If the file is a public accessible URL, attachment size doesn't add to overall workflow size.
***
## Dynamic workflow trigger
```go Request theme={"system"}
// Create workflow body
wfBody := map[string]interface{}{
"name": "Workflow Name",
"template": "template slug",
"notification_category": "category",
// "delay": "15m", // Chek duration format in documentation
"users": []map[string]interface{}{
{
"distinct_id": "_distinct_id_",
// if $channels is present, communication will be tried on mentioned channels only.
// "$channels": []string{"email"},
"$email": []string{"abc@example.com"},
"$androidpush": []map[string]interface{}{
{"token": "__android_push_token__", "provider": "fcm", "device_id": ""},
},
},
},
// delivery instruction. how should notifications be sent, and whats the success metric
"delivery": map[string]interface{}{
"smart": false,
"success": "seen",
},
// data can be any json string
"data": map[string]interface{}{
"key1": "value1"
},
}
wf := &suprsend.Workflow{
Body: wfBody,
IdempotencyKey: "",
BrandId: "",
}
// Call TriggerWorkflow to send request to Suprsend
_, err = suprClient.TriggerWorkflow(wf)
if err != nil {
log.Fatalln(err)
}
```
**+CountryCode Required for SMS and Whatsapp:**
For setting `$sms` and `$whatsapp`, `+` is mandatory to send along with phone number. Eg: +1 for US
For configuring a workflow from backend, you can pass following properties in your method
| 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 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](/docs/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. | **XX**d**XX**h**XX**m**XX**s 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](/docs/go-trigger-workflow-from-api#smart-delivery) | `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](https://handlebarsjs.com/guide/) language | `"data": { "key": { "key": "value", "key": "value" } },` | *Optional* |
\*\*Response structure: \*\*When you call `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
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](https://app.suprsend.com/en/staging/logs)' section. In the background, a workflow is created with the given workflow `name`.
### Bulk trigger multiple dynamic workflows
Bulk API allows you to send multiple workflow requests in a single call. There isn't any limit on number-of-records that can be added to bulk\_workflows instance. Use `.Append()` on `BulkWorkflows` instance to add however-many-records to call in bulk.
Response is an instance of `suprsend.BulkResponse` type
```go Request theme={"system"}
// Workflow: 1
wf1 := &suprsend.Workflow{
Body: map[string]interface{}{
"name": "__workflow_name__",
"template": "__template_slug__",
"notification_category": "__category__", // system/transactional/promotional
"users": []map[string]interface{}{
{
"distinct_id": "_distinct_id_",
"$email": []string{"__email__"},
},
},
},
IdempotencyKey: "",
BrandId: "",
}
// Workflow: 2
wf2 := &suprsend.Workflow{
Body: map[string]interface{}{
"name": "__workflow_name__",
"template": "__template_slug__",
"notification_category": "__category__", // system/transactional/promotional
"users": []map[string]interface{}{
{
"distinct_id": "_distinct_id_",
"$email": []string{"__email__"},
},
},
},
IdempotencyKey: "123456",
BrandId: "default",
}
// ...... Add as many Workflow records as required.
// Create bulk workflows instance
bulkIns := suprClient.BulkWorkflows.NewInstance()
// add all your workflows to bulkInstance
bulkIns.Append(wf1, wf2)
// Trigger
bulkResponse, err := bulkIns.Trigger()
if err != nil {
log.Println(err)
}
log.Println(bulkResponse)
```
```go Response theme={"system"}
// Response structure
suprsend.BulkResponse{
Status : "success",
Total : 10, // number of records sent in bulk
Success : 10, // number of records succeeded
Failure : 0, // number of records failed
FailedRecords : [],
}
suprsend.BulkResponse{
Status : "fail",
Total : 10, // number of records sent in bulk
Success : 0, // number of records succeeded
Failure : 10, // number of records failed
FailedRecords : [{"record": {...}, "error": "error_str", "code": 500}]
}
suprsend.BulkResponse{
Status : "partial",
Total : 10, // number of records sent in bulk
Success : 6, // number of records succeeded
Failure : 4, // number of records failed
FailedRecords : [{"record": {...}, "error": "error_str", "code": 500}]
}
```
***