Besides the standard web channel, CTLive can be enhanced with additional channels using Rest API. The protocol implemented is the following. The following protocol is based on the protocol implemented by Infobip (https://dev-old.infobip.com/whatsapp-business-messaging/incoming-whatsapp-messages)
NewMessage
Used to notify for a new incoming message. It can be a text message or a multimedia message.
To send a new message call the following URL
POST https://<hostname>/imchanne/message
Text Message
There are two ways how incoming messages can be forwarded to the client's end-point. They can be delivered with or without contact name.
Example of incoming message without contact name:
{
"results": [
{
"from": "385919998888",
"to": "1234",
"integrationType": "WHATSAPP",
"receivedAt": "2019-07-19T11:21:27.861+0000",
"messageId": "ABEGOFl3VCQoAhAqnlmSd2FKPOaraEaS0rPQ",
"pairedMessageId": null,
"message": {
"type": "TEXT",
"text": "Support hello"
}
}
]
}
Example of the incoming message with the contact name:
{
"results": [
{
"from": "385919998888",
"to": "1234",
"integrationType": "WHATSAPP",
"receivedAt": "2019-07-19T11:23:26.998+0000",
"messageId": "ABEGOFl3VCQoAhBalbc6rTQT6mgS29EmGZ7a",
"pairedMessageId": null,
"message": {
"type": "TEXT",
"text": "Support hello"
},
"contact": {
"name": "Frank"
}
}
]
}
Notes:
Parameter names | Type | Description |
|---|---|---|
from | string | From Identifier |
to | string | To identifier |
integrationType | string | channel name |
receivedAt | string | Timestamp indicating when the message has been received by the platform |
messageId | string | unique identifier for message. In case of network problem it’s possibile to resend the same message with the same messageID. |
pairedMessageID | string | reference to another message for “quote” feature |
message.type | string | TEXT for text messages |
message.text | string | content of the text message |
contact.name | string | name linked with the from identifier if available |
Image message
An image message is identified bu type “IMAGE” and the payload is transferred through a URL called by CTLive when the message is received. Url is requested using GET only once, because after that, it’s stored for any use.
{
"results": [
{
"from": "385919998888",
"to": "1234",
"integrationType": "WHATSAPP",
"receivedAt": "2018-09-10T11:27:17.980+0000",
"messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
"message": {
"type": "IMAGE",
"caption": "Image Caption",
"url": "https://{base_url}/123455"
}
}
]
}
Document message
Document message is very similar to image message, except for the type “DOCUMENT”. The caption is intended to be used for the filename.
{
"results": [
{
"from": "385919998888",
"to": "1234",
"integrationType": "WHATSAPP",
"receivedAt": "2018-09-10T12:10:18.379+0000",
"messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
"pairedMessageId": null,
"message": {
"type": "DOCUMENT",
"caption": "Document caption",
"url": "https://{base_url}/whatsapp/1/senders/447796344125/media/c256e11d-a7e9-4dbb-aa9c-2a6028ddf7e8"
},
}
]
}
Outbound Message
Outbound messages are sent by CTLive to a configurable URL with Basic authentication with a specific payload for each message type. The scenarioKey it’s a specific id linked with the account to be used as source number.
Text message
{
"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
"destinations": [
{
"to": {
"phoneNumber": "41793026727"
}
}
],
"whatsApp": {
"text": "This WhatsApp message will be delivered to WhatsApp application on the user device."
},
}
Response format
If successful, the response header HTTP status code will be 200 OK and the message will be sent.
If you try to send the message without authorization, you will receive a 401 Unauthorized error.
{
"messages": [
{
"to": {
"phoneNumber": "41793026731"
},
"status": {
"groupId": 1,
"groupName": "PENDING",
"id": 7,
"name": "PENDING_ENROUTE",
"description": "Message sent to next instance"
},
"messageId": "50c24400-124f-4678-9f4b-309e994a4deb"
}
]
}
Image message
If you would like to send WhatsApp messages containing text and image, please check the example provided below.
Parameter | Type | Description |
|---|---|---|
text |
| Text of the message that will be sent. |
imageUrl |
| URL of the image sent |
{
"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
"destinations": [
{
"to": {
"phoneNumber": "41793026727"
}
}
],
"whatsApp": {
"text": "Get your message across!",
"imageUrl": "<url>"
},
}
Document message
If you would like to send messages containing document file, please check the example provided below.
Parameter | Type | Description |
|---|---|---|
text |
| Name of the file that will be sent. |
fileUrl | string | URL of the file sent |
{
"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
"destinations": [
{
"to": {
"phoneNumber": "41793026727"
}
}
],
"whatsApp": {
"text": "File caption",
"fileUrl": "https://www.documentUrl.com"
}
}
Delivery Message
CTLive can be informed about the delivery status of outbound messages posting the following URL https://<hostname>/imchanne/message
{
"results": [{
"bulkId": "",
"status": {
"id": 5,
"groupId": 3,
"groupName": "DELIVERED",
"name": "DELIVERED_TO_HANDSET",
"description": "Message delivered to handset"
},
"messageId": "fb469d73-d362-463f-b30f-1e959b53badc",
"doneAt": "2019-04-09T16:01:56.494-0300",
"sentAt": "2019-04-09T16:00:58.647-0300",
"to": "41793026731",
"channel": "WHATSAPP"
}]
}
Seen Reports
CTLive can be informed about the seen status of outbound messages posting the following URL https://<hostname>/imchanne/message
{
"results": [
{
"messageId": "1215f543ab19-345f-adbd-12ad31451ed25f35",
"to": "41793026731",
"sentAt": "2018-12-12T11:21:57.793+0000",
"seenAt": "2018-12-12T11:21:58.251+0000"
}
]
}