RCS API for Messaging

This API Collection is meant to send outgoing messages from Business. It covers messages sent with Pre-Approved Templates and without using any Template.

Overview

This API Collection is related to sending out messages to customer or users. These are called outgoing messages from business point of view.

Using a single API Route, you can send messages with different kind of contents with or without a template. The JSON Payload is different for different type of contents. Therefore, the following sections explains about how to prepare the JSON Payload to cover different type of messaging.

Send Message using India Templates

Following section explains how to send a message using a pre-approved template. The API Call may take dynamic content or data to replace related placeholders in the template.

Please note that when business sends a message, it is necessary to use a pre-approved template in India. However, in all other contexts whether responding to a user-initiated message or sending follow-up messages within 24 hours in a Conversation, there are no restrictions on the use of pre-approved templates.

• API Route: https://api.enablex.io/rcs/v1/messages/templates
• Request: POST
• Authorization: Bearer Token / Basic

JSON Payload Example# 1: Refer the following JSON Payload to send message using a Template with Text Content that doesn’t have any data placeholder.

{
	"type": "{type of message}",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
	"template": {
		"name": "{template name}",
	},
	"fallback_text": "{message}",
	"ttl": {time to live},
	"expire_time": "{expiry time YYYY-MM-DD HH:MM:SS}"
}

JSON Payload Example# 2: Refer the following JSON Payload to send message using a Template with Text Content. If the body of the template definition had placeholder variable, you must provide data for all Placeholder Variables.

{
	"type": "{type of message}",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
	"template": {
		"name": "{template name}",
		"variables": {
			"var1": "{value of variable var1}",
			"var2": "{value of variable var2}",
		}		
	},
	"fallback_text": "{message}",
	"ttl": {time to live},
	"expire_time": "{expiry time YYYY-MM-DD HH:MM:SS}"
}

Payload Explanation: This is to explain all common keys and objects used in payload to send message of different kind using pre-approved template.

Object Explanation: template Object

Success Response:

{
    "code": 200,
    "message": "Message request has been created",
    "message_id": "{String}"
}

**Response Explanation:** Success condition

|Key / Object|	Data Type|	 Description|
|------------|-----------|-------------|-------------|
|`code`	|Number	| 200 for success. |
|`message`|String	| Detailed description |
|`message_id`|String	| Unique Identifier of the message queued. DLR notifications will be received against this. |

Send Message without Template

Following section explains how to send a message without a pre-approved template.

If Business is not in India, business can send message to users without template anytime. In India, Business can send message without template only after being responded by a user.

The first message that business sends responding to user's message creates a conversation window of 24 hours from that time. Within a conversation period, any message can be sent by business to the user without using a template. Such follow up messages are also called Session Messages.

• API Route: https://api.enablex.io/rcs/v1/messages
• Request: POST
• Authorization: Bearer Token / Basi

Standard Payload

JSON Payload: This is a standard format of JSON used to send messages with different type of contents.

{
	"type": "{type of message}",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
	 
        // key & object definitions appear related to the 
	// value of "type" key. Different type has 
	// differnt key/objects to define the data

	"fallback_text": "{message}",
	"ttl": {time to live},
	"expire_time": "{expiry time YYYY-MM-DD HH:MM:SS}"
}

Payload Explanation

Success Response Format

Success Response: Standard Response format

{
	"code": 200,
	"message": "Message request has been created",
	"message_id": "{String}"
}

**Response Explanation:** Standard Response

|Key / Object|	Data Type|	 Description|
|------------|-----------|-------------|-------------|
|`code`	|Number	| 200 for success. |
|`message`|String	| Detailed description |
|`message_id`|String	| Unique Identifier of the message queued. DLR notifications will be received against this. |

Send Message with Text Content

Text messages are sent with type:text. You can define a text of upto 2500 characters. Further you can definesuggestions, an array of suggestion objects for users to respond with interactive elements.

JSON Payload Example: Refer the following JSON Payload to send text message.

{
	"type": "text",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
	"text": "{plain text}",
	"suggestions": [
		{suggestion}
	],
	"fallback_text": "{message}",
	"ttl": {time to live},
	"expire_time": "{expiry time YYYY-MM-DD HH:MM:SS}"
}

Payload Explanation: Related to Text Content only.

Read more....

• Suggestions

Send Message with Rich Card Content

A messages with rich media content can be sent with type:card. You can define a media content in the Card Object. Further a card can have suggestions, an array of suggestion objects for users to respond with interactive elements.

JSON Payload Example: Refer the following JSON Payload to send Rich Card Content.

{
	"type": "card",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
	"card": {
		"title": "{Plain Text}",
		"description": "{Plain Text}",
		"url": "{https url of media file}",
		"id": "{uploaded file-id}",
		"thumbnail_url": "{https url of media file}",
		"thumbnail_id": "{uploaded file-id}",
		"suggestions": [
			{ suggestion }
		]
	},
	"fallback_text": "{message}",
	"ttl": {time to live},
	"expire_time": "{expiry time YYYY-MM-DD HH:MM:SS}"
}

Payload Explanation: Related to Rich Card Content only.

Object Explaination: card Object related explaination

Read more....

• Rich Card Specification
• Suggestions

Send Message with Rich Card Carousel

A messages with a carousel of 1-10 Rich Cards with type:carousel. It's a stack of Rich Cards, played as Carousel or Slideshow. Further each card can have suggestions, an array of suggestion objects for users to respond with interactive elements.

JSON Payload Example: Refer the following JSON Payload to send Rich Card Carousel Content.

{
	"type": "carousel",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
	"carousel": [
		{
			"title": "{Plain Text}",
			"description": "{Plain Text}",
			"url": "{https url of media file}",
			"id": "{uploaded file-id}",
			"thumbnail_url": "{https url of media file}",
			"thumbnail_id": "{uploaded file-id}",
			"suggestions": [
				{ suggestion }
			]
		}
	],
	"fallback_text": "{message}",
	"ttl": {time to live},
	"expire_time": "{expiry time YYYY-MM-DD HH:MM:SS}"
}

Payload Explanation: Related to Rich Card Carousel Content only.

Object Explaination: card Object related explaination arleady given in the previous section.

Read more....

• Rich Card Specification
• Rich Card Carousel Specification
• Suggestions

Revoke a sent Message

Any message sent is queued for delivery at RBM. If a message couldn't be delivered for transactional reason, the RBM keeps the message in queue for 30 days since it has been injected into the Queue unless a ttl or expire_time is defined in the API Payload.

For any reason, if a queued message needs to be revoked befored delivery, the following API endpoint may be used.

When the RBM platform receives a revocation request, the platform returns 200 OK. The 200 OK response doesn't confirm whether or not the message was revoked. If the revocation was successful, the RBM platform stops trying to deliver the message, and it's deleted from the user's queue.

• API Route: https://api.enablex.io/rcs/v1/messages/revoke/$msg_id
• Request: DELETE
• Authorization: Bearer Token / Basic
• Embeded Variable in URL: $msg_id (Message ID to be revoked)

Mark Incoming Message as "Read"

Any incoming message for business can be marked as "Read". This is to notify the end user that his message is read by business.

• API Route: https://api.enablex.io/rcs/v1/messages/read
• Request: POST
• Authorization: Bearer Token / Basic

JSON Payload example:

{
	"request_id": "{Request ID }",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
}

Send Typing Indicator

When enduser types in message, related notification is sent to business through Webhook. Using this API endpoint, business can send a typing indicator to user to notify that business is typign response to him.

• API Route: https://api.enablex.io/rcs/v1/indicators/typing
• Request: POST
• Authorization: Bearer Token / Basic

JSON Payload example:

{
	"request_id": "{Request ID}",
	"phone": "{mobile number with country code}",
	"agent": "{agent name}",
}

Webhook Notifications

Delivery Status Updates JSON: An Outgoing Message changes it’s status in its life time as it passes through different stages until its read by the user. All updates on Deliver Status are notified on Webhook in the following format:

{
	"event_type": 'status',
	"message_id": '{String}',
	"message_status": '{String}',
	"timestamp": '{String}',	
	"phone": '{String}',
	"agent": '{String}',
	"failure_reason": '{String}'
}

JSON Explanation

|Key| Data Type|Description| |------------|-----------|-------------|-------------| |event_type |String | Value status stands for Message Delivery Status. | |message_id|String | Unique Message ID of the original message against which the status update being received.| |message_status|String | Enumerated data: SENT, FAILED, READ, REVOKED, DELIVERED| |timestamp|String | Timestamp in UTC. Format: 2024-06-24T06:42:16.950Z| |phone|String | End User Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)| |agent|String |RBM Agent Name| |failure_reason|String |Optional. Appears only for message_status: FAILED. Descriptive reason for delivery failure.|