SMS Service Provider

Adding your SSP 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 SSP 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. Service provider's test credentials.

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

3. A static endpoint that listens to incoming HTTPS POST requests and adheres to the specified schema for sending SMS. Note that this needs to be a single static endpoint. If you have multiple such endpoints based on, for example, geography, you will have to accept WebEngage requests on a single endpoint and then route them accordingly.

4. The request authentication method (Basic authentication or Bearer authentication).

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

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

   • In the 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.

6. If your clients will be sending SMS to Indian consumers, kindly let us know so that we enable PEID and TemplateID fields for your configurations and share details accordingly.

7. Status code management.

8. WebEngage comes with three servers: Saudi Arabia, Indian 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.

Configuring Delivery Status Notifications

WebEngage provides an endpoint security token for Delivery Status Notifications (DSN) that makes it easier for our clients to track their campaign's performance in their WebEngage dashboard.

What are Delivery Status Notifications?

Delivery Status Notifications are asynchronous updates to messages (for example, SMS Delivered, Bounced, Rejected etc.) that the service provider sends to WebEngage. This is shown in the flowchart below.

WebEngage Support will then process the request if there is a mutual client willing to try out the integration and add the service provider in private beta mode on WebEngage dashboard.

1. The service provider is required to POST Delivery Status Notifications (DSNs) i.e. SMS sent, SMS failed, etc. on the static endpoint.
   1. For US Server https://st.webengage.com/tracking/events
   2. For IN Server https://st.in.webengage.com/tracking/events
   3. For KSA Server https://st.ksa.webengage.com/tracking/events
2. The service provider will be provided with a security token which needs to be included as a Authorization header in the POST request of DSNs.

• For example: Authorization: Bearer <Security Token>. This token will remain the same and should not be shared to ensure security. In case there is a need to change the token, the service provider should reach out to WebEngage Support to get a new token.

3. Please follow the below format for the POST body for DSN:

{
    "version": "1.0",
    "messageId" : "webengage-message-id",
    "toNumber" : "919999999999",
    "status" : "sms_sent",
    "statusCode" : 0
}

WebEngage will respond to the Delivery Status Notification (DSN) with an HTTP 2XX response code and will enqueue the event to process it.

🚧

Skip to: List of DSN Status Codes

Testing Integration

You can test your integration using Postman. Here's how you can configure the Postman Test Environment:

Step 1: Import the collection of APIs which will help you test several use-cases.

Step 2: Configure the Postman environment with your account data.

Environments are a group of variables & values, that allow you to quickly switch the context for your requests and collections. Here's how you can go about it:

• Step 1: Click on the settings button next to the environment selector dropdown on the top right.

• Step 2: Select WebEngage SMS SSP Test Environment. In doing so, you will see the following keys. Edit their values as per your test environment.

  a. test-phone: Phone number on which you want to receive test messages
  b. sender-id: Phone number from which you want to send test messages.
  c. api-end-point: API endpoint of your integration
  d. username: Username of your Basic Auth. Leave the value as it is if you're using Bearer Auth.
  e. password: Password of your Basic Auth. Leave the value as it is if you're using Bearer Auth.
  f. api-key: API key (token) for Bearer Auth. Leave the value as it is if you're using Basic Auth.
  g. authorization: Leave as it is.

Step 3: Once you have set up the environment, you are ready to test your integration. Here's how you can go about it:

• Step 1: Open Postman Collection Runner by clicking on Runner button on the top of Postman window.

• Step 2: Select the Collection with the name WebEngage SMS SSP Test Suite and Environment with the name WebEngage SMS SSP Test Environment.

• Step 3: Click the Run button. Postman will then start testing your APIs and will show you the report.

On completion of the above steps, the service provider will continue to function in private beta mode for mutual clients and will be later made public after ensuring the QoS and functionality tests.

Request

The service provider should accept the following payload as a part of the request to send SMS.
The Content-Type header will always be application/json.

{
    "version": "1.0",

    "smsData": {
        "toNumber": "919999999999",
        "fromNumber": "PAXXXN",
        "body": "Text message body"
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "webengage-message-id",
        "custom": {
            "key1": "val1",
            "key2": "val2"
        }
    }
}

{
  "version": "2.0",
  "smsData": {
    "toNumber": "919999999999",
    "fromNumber": "PAXXXN",
    "body": "Text message body"
  },
  "metadata": {
    "campaignType": "PROMOTIONAL",
    "timestamp": "2018-01-25T10:24:16+0000",
    "messageId": "webengage-message-id",
    "custom": {
      "key1": "val1",
      "key2": "val2"
    },
    "indiaDLT": {
      "contentTemplateId": "xyz",
      "principalEntityId": "abc"
    }
  }
}

🚧

About Link Wrapping

If you are performing additional link wrapping on the links already wrapped by WebEngage (original URL) anywhere in the request payload, the wrapped domain must ask the caller to follow the original URL-encoded location.

For example, let's assume that the SMS has the following hyperlink:

<a href=“https://google.co.in/?param=%3D%3D%2B%20%20abcd”> Link </a>
We have a parameter named param with a value of ==+ abcd here.

If you are further wrapping this link, then the wrapped domain must ask the caller to follow the URL-encoded location (https://google.co.in/?param=%3D%3D%2B%20%20abcd), not the decoded one (https://google.co.in/?param===+ abcd).

Response

The service provider must synchronously respond with the appropriate statusCode. Also, the message status must be included, whether it is SUCCESS or ERROR. Refer to the examples below. If there is an asynchronous update to the message later (SMS Delivered, Bounced, Rejected etc.), that should be sent as a Delivery Status Notification.

🚧

Skip to: List of Response Status Codes

Example 1: Message Sent Successfully

HTTP 200 OK
{
    "status" : "sms_accepted"
}

Example 2: Message Cannot be Sent

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

Example 3: Payload Not Acceptable

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

Status Codes

These status codes are to be used both for synchronous responses and Delivery Status Notifications. 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.

India DLT specific Delivery Status Codes

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