TwoWay

TwoWay is an internal format which aims to solve some limitations of the traditional BusinessMessaging format. It is therefor the preferred way to connect to the router as an external party.

Concepts and Terminology

Client: The client that initiates the conversation with the host
Host: The third party system that hosts the conversation. The host can be an automated system like a chatbot, customer service platform or any other third party that is interested in receiving messages from the client.
ClientOriginated: The message was sent by and thus originated from the client.
ClientTerminated: The message was sent by the host and should be terminated on the client.

Sending messages via TwoWay

Visit the bot configuration application and select a rule set in order to get your TwoWay url endpoint.

POST https://api.cm.com/conversational/twoway/v1/accounts/{BotRouterAccountId}/adapters/{AdapterId}

The webhook must return 201 Created to indicate it has received the message (and an error status code if it didn't). Please provide the exact address of this webhook to your CM.com contact.

Authentication

TwoWay requires the X-Cm-Producttoken header to be present on the request. The Business Messaging API documentation contains instructions on retrieval of this producttoken

Receiving messages via TwoWay

In order to receive messages from the bot router, you must implement a JSON webhook. This webhook needs to implement the TwoWay format.

Format

This format can be used for both sending and receiving messages. The TwoWay format consists of three properties

chat

Field	Description	Required
id	The hash of the channel + from + to fields transposed to a guid	yes
sessionId	The unique identifier for the current session	no
accountId	The BotRouterAccountId	yes
channel	Specific protocol (WhatsApp, Apple Business Chat) being used for communication	yes
conversationClientId	The unique identifier of the client. Usualy a MSISDN but a longer hash in case of Apple Business Chat	yes
conversationHostId	The unique identifier for the third party system that hosts the conversation. Like the conversationClientId. This can be an MSISDN depending on the channel	yes
conversationClientName	The display name of the client's profile on the channel	no

conversationMessages

A list of messages. TwoWay supports different types of messages but they all share the following properties

Field	Description	Required
id	The unique identifier of the message	yes
$type	The type of message (Text, Media, Location). More types are described below	yes
direction	The direction the message is being send towards. ClientOriginated is used for MO messages (towards the client) while ClientTerminated is used for MT (towards the hosting third party)	yes

targetAdaptersInfo (only on receiving messages)

A list of target adapters to which the conversationMessages were sent

Field	Description
adapterId	The unique identifier of the targetadapter
adapterType	The type corresponding to that identifier

Supported channels

Business Messaging channels

Apple Business Chat
WhatsApp
Line
Push
RCS
SMS
Viber
Google Business Messages
Twitter
Facebook Messenger
Instagram
MobilePush
Telegram Messenger

Custom channels

CXWebConversations
WebChatbot
Robin

Feature matrix (WIP)

Not all features are supported across all channels. Make sure to check this matrix before going live to prevent unexpected behaviour.

	WhatsApp	SMS	Twitter	Facebook Messenger	Google business message	RCS
Suggestions.Reply.Description	x	x	v	x	x	x
Suggestions.Reply.Media	x	x	x	v	x	x
Media.RichCard.Carousel	x	x	x	v	v	v

Message types

Text

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [
        {
            "$type": "text",
            "text": "Hi",
            "id": "28c477f4-4ffd-43c2-8149-52273ec83465",
            "direction": "ClientOriginated",
            "createdOn": "2021-07-12T06:59:59.2158043+00:00"
        }
    ]
}

Field	Description	Required
text	The text message	yes

Media

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [
        {
            "$type": "media",
            "media": {
                "name": "Image name",
                "uri": "http://example.com/my-image.png",
                "mimeType": "image/jpeg"
            },
            "id": "f200b2f3-cd4e-404f-b7af-d36a3a010efc",
            "direction": "ClientOriginated",
            "createdOn": "2021-07-12T06:59:59.2158043+00:00"
        }
    ]
}

Field	Description	Required
media	A media object	yes

Location

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [
        {
            "$type": "location",
            "location": {
                "latitude": 51.6035675548752,
                "longitude": 4.77079096460324,
                "label": "CM.com",
                "searchQuery": "Konijnenberg 30, Breda, Noord-Brabant 4825 BD"
            },
            "id": "a021106e-6414-4187-85c6-65b1ecc7c332",
            "direction": "ClientOriginated",
            "createdOn": "2021-07-12T06:59:59.2158043+00:00"
        }
    ]
}

Field	Description	Required
location	A location object	yes

Apple Pay

note: Only supported in Apple Business Chat

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [{
        "$type": "applePay",
        "merchantName": "Merchant",
        "description": "Test payment",
        "orderReference": "733182a9-9ee3-40e9-81dc-12680df7555c",
        "recipientEmail": "[email protected]",
        "currencyCode": "eur",
        "recipientCountryCode": "nl",
        "languageCountryCode": null,
        "billingAddressRequired": true,
        "shippingContactRequired": false,
        "lineItems": [{
            "label": "My product",
            "type": "My type",
            "amount": 1.10
        }],
        "id": "6e131344-2a6d-487f-b9d2-020cdd7adb81",
        "direction": "ClientOriginated",
        "createdOn": "2021-07-12T06:59:59.2158043+00:00"
    }]
}

Field	Description	Required
merchantName	The merchant name	yes
description	A description of the product or service being purchased	yes
orderReference	A reference for the product or service being purchased	yes
recipientEmail	The recipient's email address	yes
currencyCode	A 3 character code according t ISO 4217	yes
recipientCountryCode	A 2 character code according to ISO 3166-1 Alpha 2	no
languageCountryCode	A 2 character code according to ISO 639-1 Code	no
billingAddressRequired	Whether the billing address is required for this product or service	yes
shippingContactRequired	Whether shipping contact is required for this product or service	yes
lineItems	A list of LineItem objects	yes

List picker

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [{
        "$type": "listPicker",
        "header": "My title",
        "body": "Select an option",
        "buttonTitle": "Options",
        "footer": "My footer",
        "mediaUri": "https://example.com/media.jpg",
        "buttons": [
            {
                "id": "1",
                "title": "list option 1"
            },
            {
                "id": "2",
                "title": "list option 2"
            }
        ],
        "id": "f3aeed9c-f8a2-4861-8827-dd7659675a7f",
        "direction": "ClientOriginated",
        "createdOn": "2021-07-12T06:59:59.2158043+00:00"
    }]
}

Field	Description	Required
header	The displayed title for ABC (maximum of 40 characters), header for WA	yes
body	The displayed subtitle for ABC (maximum of 40 characters), body for WA	yes
buttonTitle	WA list button title, not used for ABC	No
footer	WA only, list footer	yes for WA, no for ABC
mediaUri	The media uri	yes for ABC no for WA
buttons	Array of button definitions, (maximum for WA of 10 buttons)	yes
buttons.id	Media uri for ABC and unique identifier for WA (maximum for WA of 200 characters)	yes
buttons.title	labels/list titles (maximum for WA of 24 characters)	yes

Reply Buttons

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [{
        "$type": "replyButton",
        "header": "My title",
        "body": "Select an option",
        "footer": "My footer",
        "buttons": [
            {
                "id": "1",
                "title": "option 1"
            },
            {
                "id": "2",
                "title": "option 2"
            }
        ],
        "id": "f3aeed9c-f8a2-4861-8827-dd7659675a7f",
        "direction": "ClientOriginated",
        "createdOn": "2021-07-12T06:59:59.2158043+00:00"
    }]
}

Field	Description	Required
header	Header for reply button (maximum of 20 characters)	no
body	Body for reply button (maximum of 1024 characters)	yes
footer	Footer for reply button (maximum of 60 characters)	no
buttons	Array of button definitions, (maximum of 3 buttons)	yes
buttons.id	Id for button (maximum for WA of 256 characters)	yes
buttons.title	Titles for button (maximum of 20 characters)	yes

Text with url

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [{
        "$type": "textWithUrl",
        "text": "Example",
        "url": {
            "uri": "https://example.com/1",
            "label": "test"
        },
        "media": {
            "name": "test",
            "uri": "https://example.com/media.jpg",
            "mimeType": "image/jpg"
        },
        "id": "b5184cf0-39a7-4242-94df-c927b6073535",
        "direction": "ClientOriginated",
        "createdOn": "2021-07-12T06:59:59.2158043+00:00"
    }]
}

Field	Description	Required
url	An url object	yes
media	A media object	yes

Pass-through

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationMessages": [
        {
            "$type": "passthrough",
            "PassthroughMessageType": "WATemplate",
            "JsonContent" : {}
        }
    ]
}

Field	Description	Required
PassthroughMessageType	Type for passthrough message, currently only WATemplate	yes
JsonContent	The json content to pass through	yes