TwoWay Format

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

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

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

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.

FieldDescriptionRequired
idA hash created from the combination of client id, host id and channelYes
sessionIdThe id for the current sessionNo
accountIdThe id of the CONVERSATIONAL technical linkYes
channelThe medium being used for communication, e.g. WhatsApp or CXWebConversationsYes
conversationClientIdThe client id from which messages are sentYes
conversationHostIdThe host id to which messages are sentYes
conversationClientNameThe display name of the client on the channelNo

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.

FieldDescriptionRequired
idThe id of the messageYes
$typeThe type of the message, see Message typesYes
directionThe direction of the message, ClientOriginated is used for MO messages while ClientTerminated is used for MTYes

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.

FieldDescription
adapterIdThe id of the target adapter
adapterTypeThe 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"
        }
    ]
}
FieldDescriptionRequired
textThe textYes

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"
        }
    ]
}
FieldDescriptionRequired
mediaAn object describing the mediaYes

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"
        }
    ]
}
FieldDescriptionRequired
locationAn object describing the locationYes

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"
    }]
}
FieldDescriptionRequired
merchantNameThe merchant nameYes
descriptionA description of the product or service being purchasedYes
orderReferenceA reference for the product or service being purchasedYes
recipientEmailThe recipient's email addressYes
currencyCode3 character currency code according to ISO 4217Yes
recipientCountryCode2 character country code according to ISO 3166-1 Alpha 2No
languageCountryCode2 character country code according to ISO 639-1 CodeNo
billingAddressRequiredWhether the billing address is required for this product or serviceYes
shippingContactRequiredWhether shipping contact is required for this product or serviceYes
lineItemsA list of objects describing the line itemsYes

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"
    }]
}
FieldDescriptionRequired
headerApple Business Chat: title, max of 40 characters
WhatsApp: header
Yes
bodyApple Business Chat: subtitle, max of 40 characters
WhatsApp: body
Yes
buttonTitleApple Business Chat: -
WhatsApp: button title
No
footerApple Business Chat: -
WhatsApp: footer
ABC: No
WA: Yes
mediaUriThe media URIABC: Yes
WA: No
buttonsA list of button definitions, maximum for WhatsApp of 10 buttons)Yes
buttons.idApple Business Chat: media URI
WhatsApp: id, max of 200 characters)
Yes
buttons.titleButton title; WhatsApp: max of 24 charactersYes

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"
    }]
}
FieldDescriptionRequired
headerThe header for the reply buttons, max of 20 charactersNo
bodyThe body for the reply button, max of 1024 charactersYes
footerThe footer for the reply button, max of 60 charactersNo
buttonsA list of button definitions, max of 3 buttonsYes
buttons.idButton id; WhatsApp: max of 256 charactersYes
buttons.titleButton title, max of 20 charactersYes

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"
    }]
}
FieldDescriptionRequired
urlAn object describing the URLYes
mediaAn object describing the mediaYes

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"
    }]
}
FieldDescriptionRequired
textThe message sent as a reply to the storyYes
urlThe link to the story being replied toYes
referenceAn id of the story being replied toYes

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" : {}
        }
    ]
}
FieldDescriptionRequired
PassthroughMessageTypeType of the passthrough message, currently only WATemplateYes
JsonContentThe JSON content as belonging to the typeYes