Transactional Campaign API

A step-by-step guide to setting up the WebEngage Transactional Campaign API for your business

WebEngage's Transactional Campaign API enables you to send critical transactional messages to your users such as order confirmations, shipping details, payment invoices and so on through the channels of Push, SMS, Email, Web Push and WhatsApp. (Detailed read on how transactional campaigns work)
Please note that this API can be used only for triggering Transactional campaigns which are in Running state i.e., the campaign needs to be launched on the WebEngage dashboard before you call this API.

Here's a quick overview of how it works:





AUTHENTICATION: Bearer Authentication Scheme



curl -X POST \
  '<HOST>/v2/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/experiments/<EXPERIMENT_ID>/transaction' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ttl": 30,
    "userId": "peter",
    "overrideData": {
        "context": {
            "token": {
                "name": "Peter",
                "orderId": "ABCD1234"


Please ensure that you:

  • Replace <HOST> with the host mentioned here.

  • Replace <YOUR_WEBENGAGE_LICENSE_CODE> with your WebEngage license code.

  • Replace<YOUR_API_KEY> with your WebEngage API key.

  • Replace<EXPERIMENT_ID> with the ID of the campaign which you would like to trigger via this API.

Finding a Campaign's ID in Dashboard

Step 1: Go to the Channel & click on the campaign's name in the List of Campaigns.

Step 2: Click Show Details on the top right of the Campaign's Overview. As shown below, you will find the Campaign ID amongst other details. Please note that your campaign ID might start with tilde (~).


Click to enlarge


Here's a list of all the parameters that can be updated through the API:

ParameterData TypeDescriptionIs Mandatory?
userIdStringIdentifier for known user. Please note that the length of userId can be a maximum of 100 characters.Yes
ttlNumber (in seconds)This parameter specifies the maximum time that WebEngage should take to send your message to the user once the message has been received by WebEngage. Delays can happen sometimes because of infrastructure issues or other errors. In case of any delays, the request will be retried multiple times (in order to send the message) only for the time duration specified in the the ttl.

We use a default ttl of 60 seconds in case it is not provided.
txnIdStringA transaction ID can be provided with each request. If this is not provided then our server will generate a random ID for each request which is also returned in the response.No
overrideData.emailStringSpecify the email ID to whom the email should be sentYes (only for Email channel)
overrideData.phoneStringSpecify the phone number to whom the SMS should be sentYes (only for SMS and WhatsApp channels)
overrideData.context.tokenJSONAn object which contains values of personalized tokens which are used in the campaign.

Eg. If the campaign's message contains the following token: {{token.first_name}} then the overrideData should be:
"overrideData": { "context": { "token": { "first_name": "Peter" } } }


200 - The request has been successfully accepted.

    "response": {
        "data": {
            "txnId": "69b180f6-5731-4c4e-9816-298058f32072",
            "experimentId": "~3ekekrh",
            "userId": "peter",
            "ttl": 30


Response CodeDescription
400The request was not in an acceptable format. Possible reasons are missing parameters, bad structure etc.
404The request resources do not exist. Possible reasons are user does not exist, invalid campaign ID etc.
408The TTL of the request expired while calling the WebEngage API.
412Certain conditional checks failed for this request. One of the reasons can be that user is not reachable on that channel.
5xxSomething went wrong at WebEngage's end. Please reach out to [email protected] in case you encounter this issue.

Please feel free to drop in a few lines at [email protected] in case you have further queries. We're always just an email away!