Chat Message Specification¶

Over the Websocket and through the Chat REST API, various types of messages are sent.

Each of these messages (or actions, as we call them) corresponds to a certain media type, e.g. a text utterance, a break, a typing indicator, an image, et cetera.

In general, actions fall into two categories: operator actions and user actions. User actions are interactions with the conversation that originate from the end user side of the conversation. Operator actions, on the other hand, are actions that originate from the "bot", or more general, the operator side of the conversation.

Usually, operator actions are generated automatically as a side effect of the Bubblescript code that is being executed while the conversation is running. However, when the bot does not contain any Bubblescript, operator actions can be sent explicitly through the conversation API to control the "bot" side of the conversation.

Common action fields¶

Each action will have the following fields:

Parameter	Type	Description
`type`	string	The type of message. See "message types" below.
`payload`	anything	The type-specific payload of this message. See "message types" below.
`time`	string	ISO timestamp of the time this message was created
`id`	string	The ID of the action
`delay`	integer or "infinity"	The delay (in milliseconds) that should be added after displaying the current message. When "infinity", the bot is waiting for human input.
`as`	object	A user object that is used to show that the current message is being sent as someone else, e.g. as a human operator.

Operator actions¶

In general, all actions are operator actions ("bot actions"), unless the type starts with user_. For actions that have been sent by the user, see the next section.

The payload field of the action is filled dependent on the action's type.

`type: "text"`¶

A text message that is sent from the bot to the user. The payload consists of a {"message": "the actual message"} object. The text can contain Markdown markup tags; before being displayed, the Markdown should be converted into HTML or stripped from the text when HTML is not applicable.

Example:

{
  "id": "aaa185fc-c9c1-4639-a4b3-bb159e474124",
  "payload": {
    "message": "Which department do you need?",
    "quick_replies": [
      {
        "content_type": "text",
        "title": "Sales"
      },
      {
        "content_type": "text",
        "title": "Customer Support"
      }
    ]
  },
  "time": "2021-04-12T12:38:04.905079Z",
  "type": "text"
}

Example with as parameter:

{
  "as": {
    "first_name": "Arjan",
    "last_name": "Scherpenisse",
    "profile_picture": "https://s3.eu-west-1.amazonaws.com/bsqd-out/image/3d635486-f626-4311-b3ef-5a25be1e8ab9-200x200.jpg",
    "user_id": "9d9470-0f94-4912-925a-50f5d7b6321a"
  },
  "id": "d49c18c9-3c35-481f-bf8f-d66310dc6a49",
  "payload": {
    "message": "How can I help you?"
  },
  "time": "2021-04-12T12:59:15.054504Z",
  "type": "text"
}

`type: "typing"`¶

Instruction to show or hide the typing indicator for the bot. The payload will be a boolean which is either true to show the typing indicator, or false to hide it.

Example:

{
  "id": "0bfbe352-26b3-42c0-8986-9a2f2e09c3a3",
  "payload": true,
  "time": "2021-04-12T12:38:04.700839Z",
  "type": "typing"
}

`type: "location"`¶

Shows a location marker. The payload will be a JSON object with a lat and a lon field to show the actual coordinate of the location marker.

`type: "media"`¶

Shows a media item. The payload will be a JSON object with a url to the URL of the media item, and a kind field that is either audio, video, image or file.

Optionally, a caption attribute can be set to provide a description of the media item.

Example:

{
  "id": "650cef6a-468e-4cd6-83c7-830582e0bb6f",
  "payload": {
    "kind": "image",
    "url": "https://s3.eu-west-1.amazonaws.com/bsqd-out/image/31f5ceef-bb42-4b8d-b2ef-7ba41c5e4ba7-1280x1280.jpg",
    "caption": "this is a caption"
  },
  "time": "2021-04-12T13:04:53.796118Z",
  "type": "media"
}

`type: "location"`¶

Send a location pin. The payload needs to be a JSON object with a lat and a lon attribute.

{
  "id": "650cef6a-468e-4cd6-83c7-830582e0bb6f",
  "payload": {
    "lat": 1, "lon": 2
  },
  "time": "2021-04-12T13:04:53.796118Z",
  "type": "location"
}

`type: "contact"`¶

Send a contact card. The payload needs to be a JSON object with a valid contact card payload, like the full example here:

{
  "id": "650cef6a-468e-4cd6-83c7-830582e0bb6f",
  "payload": {
    "addresses": [
      {
        "city": "City",
        "country": "Country",
        "street": "Street",
        "zip": "1234AB"
      }
    ],
    "birthday": "2022-12-31",
    "emails": [
      {
        "email": "john.doe@example.com"
      }
    ],
    "name": {
      "first_name": "John",
      "formatted_name": "John Doe",
      "last_name": "Doe"
    },
    "org": {
      "company": "Acme"
    },
    "phones": [
      {
        "phone": "+31612345678"
      }
    ],
    "urls": [
      {
        "url": "https://example.com"
      }
    ]
  },
  "time": "2021-04-12T13:04:53.796118Z",
  "type": "contact"
}

`type: "template"`¶

text template¶

The template_type: "text" template sends the given text template to the user.

In case of conversations on Whatsapp, the template_id corresponds to the ID as given in the whatsapp template manager. The parameters object must be filled with all parameters required for the given template.

{
  "type": "template",
  "payload": {
    "template_type": "text",
    "template_id": "ticketupdate1",
    "parameters": {
      "1": "Pete",
      "2": "12345"
    }
  }
}

The template must exist in the language the conversation is in. For single-language bots, ensure that the bot's default language is set to the right value before starting the conversation.

To send a specific language version of the template, independent of the conversation's locale, add the locale_override parameter:

{
  "type": "template",
  "payload": {
    "template_type": "text",
    "template_id": "ticketupdate1",
    "locale_override": "nl",
    "parameters": {
      "1": "Pete",
      "2": "12345"
    }
  }
}

On non-Whatsapp channels, the text template is ignored

email template¶

For conversations that are on the email channel, specifying template_type: "email" will cause an email to be sent. See the email channel documentation on the exact format and fields of the email template.

On non-Email channels, the text template is ignored

`type: "emit"`¶

Indicates that an event has been emitted to the client, using Bubblescript's emit statement. The payload object will contain a event string with the name of the event, and (again) a payload field with the payload that was sent with the event.

{
  "id": "362511af-5e08-45ce-8576-9bf4a374357e",
  "payload": {
    "name": "my_event",
    "payload": "hi",
  },
  "time": "2021-04-12T13:00:20.682855Z",
  "type": "emit"
}

The following actions have been sent by the bot user; the end-user facing side of the conversation.

`type: "user_message"`¶

A text message as typed by the user

{
 "id": "901cd1ab-b233-4ed3-aea8-79d5851afcae",
 "payload": {
   "input_type": "keyboard",
   "text": "I need help now",
   "type": "text"
 },
 "time": "2021-04-12T13:01:04.709457Z",
 "type": "user_message"
}

payload.input_type can be one of keyboard, touch or voice, depending on how the message was entered

payload.type depicts the kind of message; usually a user message is a text message but the following other types are also possible: form, item_picker, numeric, wait. In those cases the payload.data field contains the input-method specific value; payload.text is filled with a "rendered" version of the data.

`type: "user_attachment"`¶

An attachment as sent by the user.

{
 "id": "12de2c67-a574-4ef6-9126-16b614893321",
 "payload": {
   "metadata": {},
   "type": "image",
   "url": "https://s3.eu-west-1.amazonaws.com/bsqd-out/image/31f5ceef-bb42-4b8d-b2ef-7ba41c5e4ba7-1280x1280.jpg"
 },
 "time": "2021-04-12T13:02:59.274197Z",
 "type": "user_attachment"
}

url and type are required

Valid values for payload.type are: image, video, audio and file.

metadata can be filled with any JSON metadata that is available

`type: "user_location"`¶

A location marker as sent by the user

{
  "id": "cd3ef06c-7569-44c2-bc12-411cb098dc87",
  "payload": {
    "lon": 4.8393931,
    "lat": 52.3774504
  },
  "time": "2021-04-12T13:02:15.845349Z",
  "type": "user_location"
}

`type: "user_event"`¶

An event as sent to the conversation by the user

{
  "id": "362511af-5e08-45ce-8576-9bf4a374357e",
  "payload": {
    "name": "$presence",
    "payload": "away"
  },
  "time": "2021-04-12T13:00:20.682855Z",
  "type": "user_event"
}

Chat Message Specification¶

Operator actions vs user actions¶

Common action fields¶

Operator actions¶

`type: "text"`¶

`type: "typing"`¶

`type: "location"`¶

`type: "media"`¶

`type: "location"`¶

`type: "contact"`¶

`type: "template"`¶

text template¶

email template¶

`type: "emit"`¶

User actions¶

`type: "user_message"`¶

`type: "user_attachment"`¶

`type: "user_location"`¶

`type: "user_event"`¶

Chat Message Specification¶

Operator actions vs user actions¶

Common action fields¶

Operator actions¶

type: "text"¶

type: "typing"¶

type: "location"¶

type: "media"¶

type: "location"¶

type: "contact"¶

type: "template"¶

text template¶

email template¶

type: "emit"¶

User actions¶

type: "user_message"¶

type: "user_attachment"¶

type: "user_location"¶

type: "user_event"¶

`type: "text"`¶

`type: "typing"`¶

`type: "location"`¶

`type: "media"`¶

`type: "location"`¶

`type: "contact"`¶

`type: "template"`¶

`type: "emit"`¶

`type: "user_message"`¶

`type: "user_attachment"`¶

`type: "user_location"`¶

`type: "user_event"`¶