WhatsApp Service Provider

How a WhatsApp Service Provider can integrate its platform WebEngage

Adding your WhatsApp Service Provider (WSP) to WebEngage enables you to extend your services to over 40,000 global users and makes it easier for your existing clients to start using your services through their WebEngage dashboard.

How to Initiate WSP Integration

We'd love to add you to our Service Partner Network! Please feel free to initiate a conversation by dropping an email at [email protected] with the following details:

  1. Your test credentials. For example, you could share a username-password OR API Key and an API endpoint where we can POST requests.

  2. A logo of the service provider with a minimum width of 370 px in PNG/JPEG format.

  3. A static endpoint URL that listens to incoming HTTPS POST requests and adheres to the specified schema for sending WhatsApp messages.

    • Please note that this needs to be a single static endpoint. If you have multiple endpoints dedicated to various geographies and so on, then you will need to accept WebEngage requests on a single endpoint and route them accordingly for delivery.
  4. The request authentication method (Basic authentication or Bearer authentication).

  5. Input fields to be shown to the client on WebEngage dashboard. For example: API Key or Username and Password.

    • In case of API Key, the POST request will contain the header Authorization: Bearer API_KEY.

    • In case of Username and Password, the POST request will contain the header Authorization: Basic BASE_64(USERNAME:PASSWORD).

      • For example, if your username is 'webengage' and password is 'admin' then the Authorization header will be Basic d2ViZW5nYWdlOmFkbWlu. The string d2ViZW5nYWdlOmFkbWlu is the Base64 encoded version of the string webengage:admin.

Our support team will process your request if a mutual client agrees to test your WSP in private beta mode on our dashboard before we make it available for all our clients.

SECTION 1: The flow of the message will be as follows:

WebEngage will send message to the WhatsApp Service Provider (WSP) and WSP will reply synchronously to the message received with respective Status Codes given in the last section of this documentation.

WSP will reply back to WebEngage webhook (i.e. static endpoint which can be found on WebEngage dashboard following: Data Platform > Integrations > WhatsApp Setup (Configure) > ACTIONS (WSP) > View Webhook URL.) for the delivery report (i.e. Delivery Status Notification (DSN)) asynchronously.

1. WebEngage WhatsApp Request to WSP

As depicted in SECTION 1 point 1, WebEngage will send WhatsApp messages to WSP in the following given payload format and WSP needs to reply synchronously to the message with Status Codes provided in the last section of this documentation.

Key points for API request from WebEngage to WSP:

  1. At the time of integration, WebEngage allows WSP to either accept message or templateVariables in the payload request from WebEngage to WSP. templateVariables is a list of string of template variables provided by user as per template and message is the actual generalization of the user’s template with the given template variables.

e.g. if the template is: hello {{1}}, welcome to new {{2}} and template variables i.e. {{1}} and {{2}} are john and world, then the actual generalized message will be: hello john, welcome to the new world and templateVariables will be: ["john", "world"].

  1. templateData provided in the given below payload will only contain either message or templateVariables as per WSP’s choice at the time of integration. WSP will never receive both messages as well as templateVariables.

  2. The Content-Type header will always be application/json. We’ll also provide support for adding custom headers (specific to individual WSP) while the user creates WhatsApp WSP configuration on WebEngage dashboard.

Request format of payload from WebEngage to WSP

{
    "version": "1.0",
    "whatsAppData": {
        "toNumber": "919999999999",
        "fromNumber": "44000000099",
        "templateData": {
            "templateName": "templatexyz",
            "message": "hello john, welcome to new world",
            "templateVariables": ["john", "world"],
                        "type" : "TEXT",
      "buttonUrlParam" : "XYZ.pdf", // In the case of dynamic CallToAction  
            "language": "en"
        }
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "webengage-message-id"
    }
}
{
  "version": "1.0",
  "whatsAppData": {
    "toNumber": "919999999999",
    "fromNumber": "44000000099",
    "templateData": {
      "templateName": "templatexyzVIDEO",
            "message": "hello john, welcome to new world",
      "templateVariables": ["john", "world"],
      "type" : "VIDEO",
      "mediaUrl":"https://www.webenagege.com/webengage-logo.png",
      "buttonUrlParam" : "XYZ.pdf", // In the case of dynamic CallToAction
      "language": "en"
    }
  },
  "metadata": {
    "campaignType": "PROMOTIONAL",
    "timestamp": "2018-01-25T10:24:16+0000",
    "messageId": "webengage-message-id"
  }
}
{
  "version": "1.0",
  "whatsAppData": {
    "toNumber": "919999999999",
    "fromNumber": "44000000099",
    "templateData": {
        "templateName": "templatexyzIMAGE",
            "message": "hello john, welcome to new world",
      "templateVariables": ["john", "world"],
      "type" : "IMAGE",
      "mediaUrl":"https://www.webenagege.com/webengage-logo.png",
      "buttonUrlParam" : "XYZ.pdf", // In the case of dynamic CallToAction
      "language": "en"
    }
  },
  "metadata": {
    "campaignType": "PROMOTIONAL",
    "timestamp": "2018-01-25T10:24:16+0000",
    "messageId": "webengage-message-id"
  }
}
{
  "version": "1.0",
  "whatsAppData": {
    "toNumber": "919999999999",
    "fromNumber": "44000000099",
    "templateData": {
      "templateName": "templatexyzDOC",
            "message": "hello john, welcome to new world",
      "templateVariables": ["john", "world"],
      "type" : "DOCUMENT",
      "mediaUrl":"https://www.webenagege.com/webengage-logo.png",
            "fileName": "<file-name if added>",
      "buttonUrlParam" : "XYZ.pdf", // In the case of dynamic CallToAction
      "language": "en"
    }
  },
  "metadata": {
    "campaignType": "PROMOTIONAL",
    "timestamp": "2018-01-25T10:24:16+0000",
    "messageId": "webengage-message-id"
  }
}
{
 { 
  "version": "1.0",
  "whatsAppData": {
    "toNumber": "919999999999",
    "fromNumber": "44000000099",
    "templateData": {
            "templateName": "templatexyzDOC",
            "message": "hello john, welcome to new world",
        "templateVariables": ["john", "world"],
      "type" : "LOCATION",
      "longitude":15.946519,
      "latitude":45.946519,
      "locationName":"Name of the location",       
      "locationAddress":"Address",
      "buttonUrlParam" : "XYZ.pdf", // In the case of dynamic CallToAction
      "language": "en"
    }
  },
  "metadata": {
    "campaignType": "PROMOTIONAL",
    "timestamp": "2018-01-25T10:24:16+0000",
    "messageId": "webengage-message-id"
  }
}

Key

Description

version

Indicates the payload contract. If there is any change in the payload structure in future, the version will be updated.

toNumber

The recipient’s encoded phone number along with prefixed country code.

fromNumber

The WhatsApp Business Number you are using to send the campaign.

templateName

Name of the whitelisted template being used by you.

message

message to be delivered to user (generalised message as per template and template variables). It will be provided if you accept this in place of templateVariables.

templateVariables

List of string values of template variables in exact sequence as per template. It will be provided if you accept this in place of message

This key is included in the payload only if you select Send Personalization Variables against Request Type during configuration.

language

Message template language supported by WhatsApp

buttonUrlParam

Indicates the Dynamic call to Action placeholder value

This key is included in the payload only if Dynamic CTA buttons are added in the WhatsApp template

type

Indicates the WhatsApp media template type

This key is included in the payload only for media templates: TEXT, VIDEO, IMAGE, DOCUMENT, LOCATION

mediaUrl

Resource URL link which is to be sent

This key is included for VIDEO, IMAGE, DOCUMENT media templates

longitude

Longitude value

This key is included for LOCATION template only

latitude

Latitude value

This key is included for LOCATION template only

locationName

Name of the location

This key is included for LOCATION template only

locationAddress

Address of the location

This key is included for LOCATION template only

Here's what each parameter included in the metadata container denotes:

Keys

Description

campaignType

The value this key in the payload can be either PROMOTIONAL or TRANSACTIONAL as selected by the user creating campaign on WebEngage dashboard.

timestamp

The time when the message was triggered from the WebEngage system. This follows the ISO date format: yyyy-MM-ddTHH:mm:ss±hhmm.

messageId

Unique ID assigned to the message which should be used in further Delivery Status Notifications to identify a message uniquely.

Example curl Request for Request Type: Send Personalization Variables

curl --location --request POST '<WSP-API-END-POINT>' \
--header 'Authorization: Bearer <API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": "1.0",
    "whatsAppData": {
        "toNumber": "919999999999",
        "fromNumber": "44000000099",
        "templateData": {
            "templateName": "templatexyz",
            "templateVariables": ["john", "world"],
            "language": "en"
        }
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "webengage-message-id"
    }
}'

Example curl Request for Request Type: Send Entire Message

curl --location --request POST '<WSP-API-END-POINT>' \
--header 'Authorization: Bearer <API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": "1.0",
    "whatsAppData": {
        "toNumber": "919999999999",
        "fromNumber": "44000000099",
        "templateData": {
            "templateName": "templatexyz",
            "message": "hello john, welcome to new world",
            "language": "en"
        }
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "webengage-message-id"
    }
}'

Examples for synchronous response for above payloads from WSP to WebEngage:

Example 1: Message Accepted Successfully

HTTP 200 OK
{
    "status" : "whatsapp_accepted",
    "statusCode": 0
}

Example 2: Message Cannot be Sent further

NOTE: If the status code is not 0, send message property too.

HTTP 200 OK
{
    "status": "whatsapp_rejected",
    "statusCode": 2000,
    "message": "Not enough credit to send message"
}

Example 3: Payload Not Acceptable

NOTE: In case there is mismatch in payload version of API contract (current is 1.0).

HTTP 400 BAD REQUEST
{
    "status" : "whatsapp_rejected",
    "statusCode" : 2010,
    "message" : "Version not supported",
    "supportedVersion" : "2.0" // Mandatory in case of statusCode 2010
}

2. Delivery Status Notification (DSN) from WSP to WebEngage

Delivery report of each message forwarded by WSP to WebEngage is called as Delivery Status Notification (DSN). It helps our clients to track their campaign's performance in their WebEngage dashboard.

As depicted in SECTION 1 point 2, DSNs are asynchronous updates to messages (e.g. WhatsApp message delivered, expired, rejected etc.) that WSP sends to WebEngage webhook.

Key points for DSN from WSP to WebEngage:

  1. WSP is required to POST DSN i.e. WhatsApp message sent, failed, etc. on the static endpoint which can be found on WebEngage dashboard following: Data Platform > Integrations > WhatsApp Setup (Configure) > ACTIONS (WSP) > View Webhook URL.

WebEngage comes with two servers: India and US servers, and it is necessary that the DSN is configured for both servers.

You can find the DSN tracking link below. The DSN Token will be provided once the integration and testing are done by the WebEngage team.

The service provider is required to POST Delivery Status Notifications (DSNs) i.e. WhatsApp Message sent, failed, etc. on the static endpoint.

For US Server http://wt.webengage.com/tracking/events
For IN Server https://wt.in.webengage.com/tracking/events

  1. WSP will be provided with:

Auth token - which needs to be included as an Authorization header in the POST request of DSNs.

e.g. Authorization: Bearer . This token will remain the same and should not be shared to ensure security. In case there is a need to change the token, WSP should reach out to WebEngage Support to get a new token.

  1. Content-Type Header for the DSN request should be application/json.

  2. WebEngage will respond to the DSN request with an HTTP 2XX response code.

Request format of DSN payload from WSP to WebEngage

{
    "version": "1.0",
    "messageId" : "webengage-message-id",
    "toNumber" : "919999999999",
    "status": "whatsapp_sent",
    "statusCode" : 0,
    "reason": "FAILED WHILE TRANSMISSION",
    "timestamp": "2018-01-25T10:24:16+0000"
}

Key

Description

version

This indicates the payload contract of the request. If there is any change in the payload structure in future, the version will be updated.

messageId

This is the unique ID assigned to the message which is used to identify a message uniquely.

This is received by the service provider in the request body. The length of this string can be up to 500 characters. The messageId provided in DSNs must be the same as that received from WebEngage in the request. You must not modify it.

toNumber

The message recipient’s phone number along with prefixed country code.

status

The message status being reported by this DSN. This can be either whatsapp_sent,whatsapp_failed or whatsapp_read.

statusCode

Status code of this DSN. This must be one of the status codes described below.

reason

It is an optional field (must be given when statusCode doesn’t fulfill failed reason, or when statusCode is 9988).

timestamp

The time when the message was triggered from the WebEngage system. This follows the ISO date format: yyyy-MM-ddTHH:mm:ss±hhmm.

Example curl Request of DSN with Auth token Passed as Header for Authorization

curl --location --request POST '<STATIC-DSN-END-POINT-OF-WEBENGAGE>' \
--header 'Authorization: Bearer <AUTH-TOKEN-PROVIDED-BY-WEBENGAGE>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": "1.0",
    "messageId" : "webengage-message-id",
    "toNumber" : "919999999999",
    "status": "whatsapp_sent",
    "statusCode" : 0,
    "reason": "sent successfully to user",
    "timestamp": "2018-01-25T10:24:16+0000"
}'

Status Code

These status codes are to be used both for synchronous responses and DSN. Refer to the Description column below for more details about the respective status. Make sure that you send the appropriate HTTP status corresponding to the status codes.

Status Code

Description

HTTP Status

0

Message delivery is successful!

200

2000

Insufficient credit balance

200

2001

The IP has not been whitelisted

401

2002

Empty message body

400

2003

Invalid mobile number

400

2004

Invalid Business Number

400

2005

Authorization failure

403

2006

User blocked the Business Number

200

2007

Maximum length of the message body has been exceeded

413

2008

The message has expired

200

2009

The message was not delivered by the operator

200

2010

Payload version unsupported.

In this case the supportedVersion is to be sent mandatorily, i.e., the version supported by the service provider. For example:

HTTP 400 BAD REQUEST
{
    "status" : "sms_rejected",
    "statusCode" : 2010,
    "message" : "Version not supported",
    "supportedVersion" : "2.0"
}

400

2011

Authentication failure (e.g. mobile number might be unverified)

401

2014

Maximum number of retries to send the message have been exhausted.

200

2015

Throttling error.

To handle the loads with increasing customer base, WebEngage has introduced autoscaling which can occasionally result in higher call rates. WebEngage supports throttling from SSP end to handle such cases. Sending this status code will activate throttling for that request and WebEngage will send that request at later time.

Note:

  1. WebEngage will retry sending the message 10 times if this status is received.
  2. Time interval between retries follows binary exponential backoff: 0ms, 200ms, 400ms, 800ms...

429

2019

The message format is invalid

400

2021

Template Missing

400

2022

Template Parameter Format Mismatch

400

2023

Template did not match

400

2024

User isn't opted in for template message

200

2025

User is not Opted in and is inactive

200

9988

Unknown or other failures

200


Did this page help you?