Trigger Workflow

Learn how to trigger multi-channel, multi-tenant workflows in SuprSend

Event based trigger

You can trigger the workflows designed on SuprSend dashboard using event trigger. Below is a sample event call to trigger payment reminder workflow. These events can either be triggered by integrating one of our frontend or backend SDKs or you can also integrate with your CDP platforms like Segment and map the events passed through these platforms as your workflow trigger.

from suprsend import Event

# Track Event Example
distinct_id = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08"
event_name = "Payment Pending"   
properties = {													
  "first_name": "User",
  "invoice_amount": "$5000",
  "invoice_id":"Invoice-1234"
} 
event = Event(distinct_id=distinct_id, event_name=event_name, properties=properties)

# Track event
response = supr_client.track_event(event)
print(response)
const { Event } = require("@suprsend/node-sdk");

// Track Event Example
const distinct_id = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08" 
const event_name = "Payment Pending"  

const properties = {													
  "first_name": "User",
  "invoice_amount": "$5000",
  "invoice_id":"Invoice-1234"
}

const event = new Event(distinct_id, event_name, properties)

// Track event
const response = supr_client.track_event(event)
response.then((res) => console.log("response", res));
import org.json.JSONObject;

import suprsend.Suprsend;
import suprsend.Event;

public class Event {
  public static void main(String[] args) throws Exception {
    trackEvent();
  }

  private static Subscriber trackEvent() throws SuprsendException {
    Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");

    String distinctId = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08"; 
    String eventName = "Payment Pending"; 

    JSONObject eventProps = new JSONObject()
      .put("first_name", "User")
      .put("invoice_amount", "$5000");
   	  .put("invoice_id", "Invoice-1234");


    Event e = new Event(distinctId, eventName, eventProps);

    // Track event
    JSONObject response = suprClient.trackEvent(e);
    System.out.println(response);
  }
ev := &suprsend.Event{
  EventName:  "Payment Pending", 
  DistinctId: "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08", 
  Properties: map[string]interface{}{													
    "first_name": "User",
    "invoice_amount": "$5000",
    "invoice_id":"Invoice-1234"
  }
}

// Send event to Suprsend by calling .TrackEvent
_, err = suprClient.TrackEvent(ev)
if err != nil {
  log.Fatalln(err)
}

📘

Please Note that the user profile should be created beforehand for distinct_id passed in your event call. If user is not present, it will discard the event call.

Here is a list of all integrations that you can use to trigger event.

TypeLanguage
Backend SDKPython
Backend SDKNode
Backend SDKJava
Backend SDKGo
HTTP APITrigger event
Frontend SDK (web)Javascript
Frontend SDK (app)Android (Kotlin)
Frontend SDK (app)React Native
Frontend SDK (app)Flutter
Customer Data Platform (CDP)Segment

Triggering workflow via API

Other way of triggering workflows is to add the entire workflow configuration in you backend code and trigger workflow via one of our backend SDK or API. This is best used for cases where dynamic user channel information or sensitive data needs to be passed at the time of sending, like sending notification to anonymous users or for OTP and authentication notifications.

Here is a list of all integrations that you can use to trigger workflow via API.

TypeLanguage
Backend SDKPython
Backend SDKNode
Backend SDKJava
Backend SDKGo
HTTP APITrigger workflow

Triggering workflow using google sheets

You can also configure your one-time notifications using google sheets. This can be used by growth or product teams to trigger one time notifications for lead generation, sales cold messaging or to send announcements and product updates. We do not recommend sending more than 10,000 notifications using google sheets as each row in google sheet trigger converts to 1 workflow request and might take a lot of time to process. Also, since triggers via google sheets are generally promotional notifications, we recommend using one of the promotional sub-categories to trigger this notification. Read more about categories and how they impact your send latencies.

Here's a step-by-step guide on how to send notifications using google sheets:

Steps to setup notification trigger in google sheets

  1. Create a template group on SuprSend account. All the static content can be designed on the template, and all the variable data defined within {{...}} will be passed from the Google Sheet at the time of trigger.

  2. Create a google sheet with following data. Each row in the sheet corresponds to one recipient.

    1. distinct_id column - this is the unique identifier of the user who needs to be notified.
    2. Dynamic data columns - you need to create one column each for the dynamic data (aka variables) in your template. Note that variable names are case sensitive. If this is the template content Hi {{name}}, your {{Event}} is scheduled at {{Schedule}}. See you there., you'll have to create a column for each template variable - name, Event, and schedule in your sheet.
    3. User Channels columns - Next, create columns for user channel details. These channel columns are necessary to pass channel information that may not be present in the user profile. It's always a good practice to include channel information if you're unsure of its presence in the user profile. You can pass channels as WA for whatsapp, Email for email and SMS for SMS. For Whatsapp and SMS, you need to enter country code infront of the mobile number as +917123xxxxxx
    4. SuprSend Status column - Fill the value TBT in rows for which you want to trigger the notification. Once, the notification is triggered, the status changes to OK


📘

Tip

Google Sheet doesn't allow to start a field with +. To enter in + format, use string function: ="+917123xxxxxx"


  1. In the Navbar of Google Sheets, go to Extensions and select Apps Script


  1. It will open Apps Script in a new tab. Remove the default information present in the editor, and copy-paste the following in the editor.
//Enter your workspace key, secret, template slug, workflow name & category
const workspace_key = "__API_KEY__";
const workspace_secret = "__API_SECRET__";
const template_slug = "__TEMPLATE_SLUG__";
const workflow_name = "__WORKFLOW_NAME__";
const category = "promotional"

// Map your column names to channels if need be
// Or ensure you use following names for your columns to directly map them to channels
// distinc_id for user's distinct id
// $sms for user's mobile number
// $email for user's email
// $whatsapp for user's whatsapp
// If you have other names of your columns you can modify following two lines accordingly
const channel_col_names = {"WA":"$whatsapp","Email":"$email","SMS":"$sms"};
const distinct_id_col_name = 'distinct_id'

//--------- No Editing required below -----------------//
function Trigger_Workflows() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var headers = data[0];
  for (var i = 1; i < data.length; i++) {
    var response = convert_row_to_payload(data[i], headers);
    if (response.status === "TBT") {
      make_api_request(
        response.payload,
        sheet.getRange(i + 1, parseInt(response.status_col) + 1)
      );
    }
  }
}

function convert_row_to_payload(data, headers) {
  let status = "";
  let status_col = -1;
  let user = {
    distinct_id: null,
    $email: [],
    $sms: [],
    $whatsapp: [],
  };
  let payload = {};
  payload.data = {};
  let private_channelkeys = ["$sms", "$whatsapp", "$email", "distinct_id"];
  for (var i = 0; i < headers.length; i++) {
    if (data[i].length !== 0) {
      if (
        channel_col_names[headers[i]] ||
        private_channelkeys.includes(headers[i])
      ) {
        if (headers[i] !== "distinct_id") {
          if (user[channel_col_names[headers[i]]])
            user[channel_col_names[headers[i]]].push(data[i]);
          if (user[headers[i]]) user[headers[i]].push(data[i]);
        } else {
          user[headers[i]] = data[i];
        }
      }
      if (headers[i] !== "SuprSend Status") {
        payload.data[headers[i]] = data[i];
      } else {
        status = data[i];
        status_col = i;
      }
    }
  }
  user["distinct_id"] = payload.data[distinct_id_col_name];
  //user["is_transient"] = true; //Uncomment if user is temporary
  payload.users = [user];
  payload.name = workflow_name;
  payload.notification_category = category;
  payload.template = template_slug;
  return {
    payload: JSON.stringify(payload),
    status: status,
    status_col: status_col,
  };
}

function make_api_request(payload, cell) {
  const uri = "/" + workspace_key + "/trigger/";
  const url = "https://hub.suprsend.com" + uri;
  const md5 = MD5(payload);
  const now = new Date().toISOString();
  const message =
    "POST" + "\n" + md5 + "\n" + "application/json" + "\n" + now + "\n" + uri;
  const byteSignature = Utilities.computeHmacSha256Signature(
    message,
    workspace_secret
  );
  const signature = Utilities.base64Encode(byteSignature);
  var options = {
    method: "POST",
    contentType: "application/json",
    headers: {
      Authorization: workspace_key + ":" + signature,
      Date: now,
    },
    payload: payload,
    muteHttpExceptions: true,
  };
  cell.setValue("Processing...");
  try {
    var response = UrlFetchApp.fetch(url, options);
    cell.setValue(response.getContentText());
  } catch (error) {
    cell.setValue("Error : " + error);
  }
}

function onOpen() {
  var ui = SpreadsheetApp.getUi();
  // Or DocumentApp or FormApp.
  ui.createMenu("SuprSend")
    .addItem("Trigger SuprSend Workflow", "Trigger_Workflows")
    .addToUi();
}

function MD5(input, isShortMode) {
  var isShortMode = !!isShortMode; // Be sure to be bool
  var txtHash = "";
  var rawHash = Utilities.computeDigest(
    Utilities.DigestAlgorithm.MD5,
    input,
    Utilities.Charset.UTF_8
  );

  if (!isShortMode) {
    for (i = 0; i < rawHash.length; i++) {
      var hashVal = rawHash[i];

      if (hashVal < 0) {
        hashVal += 256;
      }
      if (hashVal.toString(16).length == 1) {
        txtHash += "0";
      }
      txtHash += hashVal.toString(16);
    }
  } else {
    for (j = 0; j < 16; j += 8) {
      hashVal =
        (rawHash[j] + rawHash[j + 1] + rawHash[j + 2] + rawHash[j + 3]) ^
        (rawHash[j + 4] + rawHash[j + 5] + rawHash[j + 6] + rawHash[j + 7]);

      if (hashVal < 0) {
        hashVal += 1024;
      }
      if (hashVal.toString(36).length == 1) {
        txtHash += "0";
      }

      txtHash += hashVal.toString(36);
    }
  }

  // change below to "txtHash.toUpperCase()" if needed
  return txtHash;
}


You'll find following information to be added in your script from SuprSend dashboard.

DataDescription
api-keyAPI Key for your workspace. From left navigation panel, select settings -> API keys. You can read more information on Workspaces here.
api-secretAPI Key for your workspace. From left navigation panel, select settings -> API keys. You can read more information on Workspaces here.
template-slugAdd the template slug of the template that you want to trigger. You can copy the the template slug by clicking on copy icon next to the template name on template details page.
Workflow NameGive a name to identify your workflow. It'll help you locate the sent workflow on the workflow listing page. You can see the notification performance on Workflow -> Analytics page.
categoryProvide notification category. We recommend using promotional sub-category for sending engagement notifications. You can read more Notification Categories here.

  1. Save the Script, and close the tab. Reload your Google Sheets, and you will find a new option named "SuprSend" in the navigation bar. On clicking it, you will see the option to "Trigger SuprSend Workflow". On triggering, the script will pick up all the rows which have value TBT in the column name "SuprSend Status", and will make an API call to SuprSend. For the successful API call, the status will change to OK.


  1. You can check the status of your notification trigger on the Logs page.



What’s Next

Check out logs to see the status of your triggered workflow. You can refer to the error guide to debug log errors.