TwoWay format, a JSON schema specification, is designed to be used for both sending and receiving messages. It consists of four possible properties:

chat
conversationMessages
conversationEvents
targetAdaptersInfo (only on receiving messages, added automatically)

Below is described what the contents of each of these properties should be.

When calling our APIs we require an authentication token to be present. Please refer to our authentication page for details.

Properties

chat

This property contains generic data about the chat as a whole, e.g. how can it be identified and who has a place in it.

Field	Description	Required
id	A hash created from the combination of client id, host id and channel	Yes
sessionId	The id for the current session	No
accountId	The id of the CONVERSATIONAL technical link	Yes
channel	The medium being used for communication, e.g. `WhatsApp` or `CXWebConversations`	Yes
conversationClientId	The client id from which messages are sent	Yes
conversationHostId	The host id to which messages are sent	Yes
conversationClientName	The display name of the client on the channel	No

conversationMessages

A list of messages. TwoWay supports different types of messages which all require a different payload. Following properties are the generic ones that are applicable to all types.

Field	Description	Required
$type	The type of the message, see Message types	Yes
id	The id of the message	No
direction	The direction of the message, `ClientOriginated` is used for `MO` messages while `ClientTerminated` is used for `MT`	Yes
createdOn	The timestamp (UTC) at which the message was created within the Conversational Router	No

conversationEvents

A list of events. TwoWay supports different types of events, some of which require a specific payload. Following properties are the generic ones that are applicable to all types:

Field	Description	Required
$type	The type of the message, see Event types	Yes
id	The id of the event	No
createdOn	The timestamp (UTC) at which the event was created within the Conversational Router	No

targetAdaptersInfo

A list of target adapters to which the conversationMessages were sent. This list is based on the state of the ruleset at the moment of sending. It is added automatically by the Conversational Router.

Field	Description
adapterId	The id of the target adapter
adapterType	The type of the target adapter

Message types

Here we describe the supported message types. For each one an example is given and after that a definition of the required properties. These are in addition to the generic properties defined here.

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	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	An object describing the media	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	An object describing the location	Yes

Contact

{
    "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": "contact",
            "contacts": [
                {
                    "contactAddresses": [
                        {
                            "city": "Breda",
                            "country": "Netherlands",
                            "countryCode": "NL",
                            "state": null,
                            "street": "Konijnenberg 30",
                            "type": "WORK",
                            "zipCode": "4825 BD"
                         }
                    ],
                    "birthday": null,
                    "emailAddresses": [],
                    "name": {
                        "firstName": null,
                        "lastName": "Your last name",
                        "middleName": null,
                        "namePrefix": null,
                        "nameSuffix": null,
                        "formattedName": "CM Developer"
                    },
                    "organization": null,
                    "phoneNumbers": [],
                    "urls": []
                }
            ],
            "id": "a021106e-6414-4187-85c6-65b1ecc7c332",
            "direction": "ClientOriginated",
            "createdOn": "2021-07-12T06:59:59.2158043+00:00"
        }
    ]
}

Field	Description	Required
contacts	An object describing the different contacts to send	Yes
contactAddresses	A list of contact addresses related to the contact	No
birthday	Birthday of the contact	No
emailAddresses	list of email addresses related to the contact	No
name	Name information of the contact, formattedName being required	Partly
organization	The organization the contact is affiliated with	No
phoneNumbers	Phone numbers related to the contact	No
urls	Relevant URLs	No

Apple Pay

{
    "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	3 character currency code according to ISO 4217	Yes
recipientCountryCode	2 character country code according to ISO 3166-1 Alpha 2	No
languageCountryCode	2 character country 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 objects describing the line items	Yes

Listpicker

{
	"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	Apple Business Chat: title, max of 40 characters WhatsApp: header	Yes
body	Apple Business Chat: subtitle, max of 40 characters WhatsApp: body	Yes
buttonTitle	Apple Business Chat: - WhatsApp: button title	No
footer	Apple Business Chat: - WhatsApp: footer	ABC: No WA: Yes
mediaUri	The media URI	ABC: Yes WA: No
buttons	A list of button definitions, maximum for WhatsApp of 10 buttons)	Yes
buttons.id	Apple Business Chat: media URI WhatsApp: id, max of 200 characters)	Yes
buttons.title	Button title; WhatsApp: max 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": "replyButtons",
		"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	The header for the reply buttons, max of 20 characters	No
body	The body for the reply button, max of 1024 characters	Yes
footer	The footer for the reply button, max of 60 characters	No
buttons	A list of button definitions, max of 3 buttons	Yes
buttons.id	Button id; WhatsApp: max of 256 characters	Yes
buttons.title	Button title, max 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 object describing the URL	Yes
media	An object describing the media	Yes

StoryReply

{
    "chat": {
        "id": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
        "sessionId": "20210126185202",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "Instagram",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": "Bob"
    },
    "conversationMessages": [{
        "$type": "storyReply",
        "text": "That's a great looking apple pie!",
        "url": "https://some_url",
        "reference": "some_reference",
        "id": "b5184cf0-39a7-4242-94df-c927b6073535",
        "direction": "ClientOriginated",
        "createdOn": "2022-06-24T06:59:59.2158043+00:00"
    }]
}

Field	Description	Required
text	The message sent as a reply to the story	Yes
url	The link to the story being replied to	Yes
reference	An id of the story being replied to	Yes

Passthrough

Passes through the message without any processing done on it.

{
    "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 of the passthrough message, currently only `WATemplate`	Yes
JsonContent	The JSON content as belonging to the type	Yes

Event types

Here we describe the supported events. For each one an example is given followed by a definition of the required properties. These are in addition to the generic properties defined here.

Router events

These events are specific to the router and can't be sent towards TwoWay. Expect to receive (some of) these on the endpoint you've configured in the TwoWay adapter in the router.

RouterSessionEnded

Notifies you of the fact that the router session has been reset for a certain chat

{
    "chat": {
        "id": "some_chat_id_guid",
        "sessionId": "some_session_id",
        "accountId": "some_account_id_guid",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678",
        "conversationClientName": null
    },
    "conversationEvents": [
        {
            "$type": "routerSessionEnded",
            "Reason": "reason",
            "Context" : {}
        }
    ]
}

Field	Description	Required
Reason	Reason for the session termination	Yes
Context	Dictionary containing extra information passed along with the termination	No

Exernal events

These are events external parties can use to communicate intent with each other. They are not router specific and can be sent towards TwoWay.

ClientLeft

Signifies the client has left the conversation. This can also be considered an inactive state

{
    "chat": {
        "id": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678"
    },
    "conversationEvents": [
        {
            "$type": "clientLeft"
        }
    ]
}

ClientRejoined

Signifies the client rejoined the conversation.

{
    "chat": {
        "id": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "channel": "WhatsApp",
        "conversationClientId": "+316012345678",
        "conversationHostId": "00316012345678"
    },
    "conversationEvents": [
        {
            "$type": "clientRejoined"
        }
    ]
}

AgentAssigned

Signifies an agent assigned to the conversation.

{
   "chat":{
      "id": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "channel": "WhatsApp",
      "conversationClientId": "+316012345678",
      "conversationHostId": "00316012345678"
   },
   "conversationEvents":[
      {
         "$type": "agentAssigned",
         "AssignedAgent":{
            "firstName": "Geertruida",
            "lastName": "Flodder",
            "alias": "Mevrouw Flodder",
            "avatarUrl": "https://..."
         }
      }
   ]
}