RCS Service Provider

Welcome to WebEngage's Developer Hub!

RSPs can integrate their platform with the WebEngage Marketing Automation Suite using this documentation.

How to Initiate RSP 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 (e.g. Username and Password or Api Key, and API endpoint where WebEngage will post messages).

  2. A logo of the service provider with minimum width of 370 px and preferably in Adobe Illustrator file format.

  3. A static endpoint which listens to incoming HTTPS POST requests and adheres to the specified schema for sending RCS message. Note that this needs to be a single static endpoint. If you have multiple such endpoints based on e.g. 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 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.

WebEngage Support will 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.

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

  1. WebEngage will send message to the RCS Service Provider (RSP) and RSP will reply synchronously to the message received with respective Status Codes given in the last section of this documentation.
  2. RSP will 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 RSP

As depicted in SECTION 1 point 1, WebEngage will send RCS message to RSP in the following given payload format and RSP 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 RSP:

  1. At the time of integration, WebEngage allows RSP to accept parameters in the payload request from WebEngage to RSP. parameters is a Map of key value pairs of the 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 RSP’s choice at the time of integration.
  3. The Content-Type header will always be application/json. We’ll also provide support for adding custom headers (specific to individual RSP) while user creates RCS RSP configuration on WebEngage dashboard.

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

{
	"version": "1.0",
	"rcsData": {
		"toNumber": "919999999999",
		"templateData": {
			"templateId": "template1",
			"parameters": {"key1":"john", "key2":"world"}
		},
		"customData":[{
        "key": "a",
        "value": "b"
      }]
	},
	"metadata": {
		"campaignType": "PROMOTIONAL",
		"timestamp": "2018-01-25T10:24:16+0000",
		"messageId": "webengage-message-id"
	}
}
KeyDescription
versionIndicates the payload contract. If there is any change in the payload structure in future, the version will be updated.
toNumberThe recipient’s phone number along with country code as prefix.
templateIdName of template used
parametersTemplate variables with the exact name and sequence as added in dashboard.
languageMessage template language supported by RCS
timestampThe time when the message was triggered from the WebEngage system. This follows the ISO date format: yyyy-MM-ddTHH:mm:ss±hhmm.
messageIdUnique ID assigned to the message which should be used in further Delivery Status Notifications to identify a message uniquely.
campaignTypePROMOTIONAL
customDataIn this section , you can pass extra data (in Key-value pair format from the dashboard) in the payload. This is mainly used by partners if they require some custom integrations to be done for their internal systems or for particular clients.

Example curl request with parameters and API Key for authentication:

curl --location --request POST '<RSP-API-END-POINT>' \
--header 'Authorization: Bearer <API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
	"version": "1.0",
	"rcsData": {
		"toNumber": "919999999999",
		"templateData": {
			"templateId": "templatexyz",
			"parameters": {"key1":"john", "key2":"world"}
		},
		"customData":[{
        "key": "a",
        "value": "b"
      }]
	},
	"metadata": {
		"campaignType": "PROMOTIONAL",
		"timestamp": "2018-01-25T10:24:16+0000",
		"messageId": "rcs-message-id"
	}
}'

Examples for synchronous response for above payloads from RSP 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) from RSP to WebEngage

Delivery report of each message forwarded by RSP 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 RSP sends to WebEngage webhook. This is shown in the flowchart below.

Key points for DSN from RSP to WebEngage:

  1. RSP is 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. RSP 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, RSP 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 from WSP to WebEngage

{
    "version": "1.0",
    "messageId" : "webengage-message-id",
    "toNumber" : "919999999999",
    "fromNumber" : "919999999989",
    "status": "rcs_delivered",
    "statusCode" : 0,
    "reason": "Success",
    "timestamp": "2024-08-12T14:57:16+0000"
}
KeyDescription
versionThis indicates the payload contract of the request. If there is any change in the payload structure in future, the version will be updated.
messageIdThis 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.
toNumberThe message recipient’s phone number along with country code as prefix.
fromNumberThe message client’s phone number along with country code as prefix.
statusThe message status being reported by this DSN. This can be either rcs_delivered,rcs_failed or rcs_read.
statusCodeStatus code of this DSN. This must be one of the status codes described below.
reasonIt is an optional field (must be given when statusCode doesn’t fulfill failed reason, or when statusCode is 9988).
timestampThe 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 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",
    "status": "rcs_delivered",
    "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 CodeDescriptionHTTP Status
0To be sent in case of success200
1000Insufficient credit balance200
1001Number is RCS Disabled200
1002Entity was not found401
1003Template code with bot doesn’t exist400
9988Unknown400
2019Credit Insufficient400
2020Message Empty403
2021Mobile Number Invalid200
2022Sender Id is Invalid413
2005Authorization failure401
2006Exceeding max length200
2007Expired400
2008Undelivered401
2009Version Unsupported200
2017Invalid Message Format429
2011Others200
2012DND Time400
2013Maximum Retries Exhausted400
2014Rate Limit Exceeded400
2015TTL Expired200
2016Retries Expired200
2023Template Missing200
2024Template Paramenter Format Mismatch200
2025User not Opted in or Inactive200

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!