Private RSP

Private RCS Service Provider Basics

• A private RSP is an API endpoint that you expose for WebEngage to call, that acts as a proxy between WebEngage and your actual RCS service provider.
• WebEngage hits your Private RSP endpoint with a payload containing the phone identifiers, the message body and some other data.
• WebEngage expects a JSON response at that instance denoting synchronous result (request success / failure).
• WebEngage also subscribes to your Webhooks and expects later hits, passing the subsequent Delivery Status Notifications (DSNs): delivery (delivered, read or failed).

Here's how this works:

WebEngage POSTs to an API endpoint URL you provide us.

1. A unique ID UUID will always be passed in messageId in the payload to uniquely identify RCS message.
2. Body of the POST request will be in JSON format.
3. Synchronous response for the message request should be passed in the predefined format shown in following step.
4. You can configure Private RSP on WebEngage dashboard with following data:

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

1. WebEngage will send message to you, and you will reply synchronously to the message received with respective Status Codes given in the last section of this documentation.
2. You will also reply back to WebEngage webhook (i.e. static endpoint which can be found on WebEngage dashboard following: Integrations > Channels > RCS > ACTIONS (RSP) > View Webhook URL. for delivery report (i.e. Delivery Status Notification (DSN)) asynchronously.

1. WebEngage RCS Request to you

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

Key points for API request from WebEngage to you:

1. At the time of adding configuration for your Private RSP (Request Type property), WebEngage allows you to accept parameters in the payload request from WebEngage. parameters is a map of key - value pair of template variables provided by user as per template.
   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 parameters will be: {"key1":"john", "key2":"world"}.
2. templateData provided in given below payload will only contain parameters as per your choice.
3. The Content-Type header will always be application/json. We’ll also provide support for adding custom headers (specific to individual you) while user creates your Private RSP configuration on WebEngage dashboard.

Request format of payload for Text/ Rich Card/ Rich Carousel from WebEngage to you

{
  "version": "1.0",
  "rcsData": {
    "toNumber": "+919999999999",
    "sender": "<senderId>",
    "templateData": {
      "templateName": "templateName",
      "parameters": {
        "paramkey1": "paramValue1",
        "paramkey2": "paramValue2"
      }
    },
    "customData": {
      "customkey1": "customValue1",
      "customkey2": "customValue2"
    }
  },
  "metadata": {
    "campaignType": "PROMOTIONAL",
    "timeStamp": "2024-12-20T12:00:21+0000",
    "messageId": "<messageId>"
  }
}

Example curl request with parameters and headers provided by you:

curl --location --request POST '<PRIVATE-RSP-API-END-POINT>' \
--header '<HEADERS-PROVIDED-BY-YOU-IN-CONFIGURATION>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "version": "1.0",
  "rcsData": {
    "toNumber": "+919999999999",
    "sender": "<senderId>",
    "templateData": {
      "templateName": "templateName",
      "parameters": {
        "paramkey1": "paramValue1",
        "paramkey2": "paramValue2"
      }
    },
    "customData": {
      "customkey1": "customValue1",
      "customkey2": "customValue2"
    }
  },
  "metadata": {
    "campaignType": "PROMOTIONAL",
    "timeStamp": "2024-12-20T12:00:21+0000",
    "messageId": "<messageId>"
  }
}'

Examples for synchronous response for above payloads by you to WebEngage:

Example 1: Message Accepted Successfully

HTTP 200 OK
{
    "status" : "rcs_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": "rcs_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" : "rcs_rejected",
    "statusCode" : 2010,
    "message" : "Version not supported",
    "supportedVersion" : "1.0" // Mandatory in case of statusCode 2010
}

2. Delivery Status Notification (DSN) by you to WebEngage

Delivery report of each message forwarded by you 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. RCS message delivered, expired, rejected etc.) that you sends to WebEngage webhook.

Key points for DSN by you to WebEngage:

1. You are required to POST DSN i.e. RCS message sent, failed, etc. on the static endpoint which can be found on WebEngage dashboard following: Integrations > Channels > RCS > ACTIONS (RSP) > View Webhook URL.
2. You 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 <Auth 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, You should reach out to WebEngage Support to get a new token.
3. Content-Type Header for the DSN request should be application/json.
4. WebEngage will respond to the DSN request with an HTTP 2XX response code.

Request format of DSN payload by you to WebEngage

{
    "version": "1.0",
    "messageId" : "webengage-message-id",
    "toNumber" : "+919999999999",
    "sender" : "<senderId>",
    "status": "rcs_delivered",
    "statusCode" : 0,
    "reason": "Success",
    "timestamp": "2024-08-12T14:57:16+0000"
}

Example curl request of DSN with Auth token for authentication as header:

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",
  "sender": "<senderId>",
  "status": "rcs_delivered",
  "statusCode": 0,
  "reason": "sent successfully to user",
  "timestamp": "2018-01-25T10:24:16+0000"
}'

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.

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!