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:

/transaction

METHOD: POST

URL STRUCTURE: <HOST>/v2/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/experiments/<EXPERIMENT_ID>/transaction

AUTHENTICATION: Bearer Authentication Scheme

API CALL RATE-LIMIT: 100/minute

EXAMPLE

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 (~).

Parameters

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

Parameter

Data Type

Description

Is Mandatory?

userId

String

Identifier for known user. Please note that the length of userId can be a maximum of 100 characters.

Yes

ttl

Number (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.

No

txnId

String

A 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.email

String

Specify the email ID to whom the email should be sent

Yes (only for Email channel)

overrideData.phone

String

Specify the phone number to whom the SMS should be sent

Yes (only for SMS and WhatsApp channels)

overrideData.context.token

JSON

An 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" } } }

No

Response

200 - The request has been successfully accepted.

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

Errors

Response Code

Description

400

The request was not in an acceptable format. Possible reasons are missing parameters, bad structure etc.

404

The request resources do not exist. Possible reasons are user does not exist, invalid campaign ID etc.

408

The TTL of the request expired while calling the WebEngage API.

412

Certain conditional checks failed for this request. One of the reasons can be that user is not reachable on that channel.

5xx

Something 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!

Updated a day ago


Transactional Campaign API


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.