Skip to main content
  1. Botium Support
  2. Technical Reference
  3. Developer Section

The Botium Bot (bot-to-user) Message

Botium Bot Message is a common format for bot-to-user messages.

Note: Botium Connectors are converting the chatbot provider-specific bot-to-user message to a Botium Bot Message. These Bot messages can then be asserted via Botium Asserters

Live Chat Example

The (simplified) Botium Bot Message can be inspected in Botium, for example in Live Chat:



Code inspection:

Message Format

{
 "sender": "bot",
 "messageText": "Here are some buttons",
 "buttons": …,
 "media": …,
 "cards": …,
 "sourceData": {
   "request": {
     "messageText": "Show me buttons",
     "media": []
   },
   "session": {}
 },
 "nlp": {
   "intent": {
     "name": "buttons",
     "confidence": 0.8
   }
 },
 "convoStepIndex": 1
}

Fields for Capturing the UI Elements, or Audio of the Response

  • Message Text: The text message, or audio message converted to text.
  • Buttons: The button elements of the UI, with the optional button payload.
Example:
[
 {
   "text": "First Button",
   "payload": "first-button-id"
 },
 {
   "text": "Second Button",
   "payload": "second-button-id"
 }
]
  • Media: External media via “mediaUri” field, or embedded media via the “buffer” field in Base64 encoding.
Example:
[
 {
   "buffer": "...",
   "mediaUri": "https://www.botium.ai/wp-content/uploads/2020/03/logo.png",
 }
]
  • Forms: Attributes to display the card as form
Example:
[
 {
   "type": "Text",
   "name": "username",
   "label": "User name",
   "value": "Joe"
 },
 {
   "type": "ChoiceSet",
   "name": "title",
   "label": "Title",
   "value": "no",
   "options": [
     { "title": "<no title>", "value": "no" },
     { "title": "Miss", "value": "miss" },
     { "title": "Mr", "value": "mr" }
   ]
 }
]

An Entry can have the following Fields:

  • Type: ChoiceSet, RadioSet, Text, Number, Date, Time, or Toggle
  • Name: The name (ID)
  • Label: The label to display
  • Value: The current value
  • Options: The Options to choose (in case of ChoiceSet, or RadioSet
  • Cards: An array of cards

Example:

[
 {
   "text": "Botium is great!",
   "subtext": "some subtext",
   "content": "card body text",
   "image": {
     "mediaUri": "https://www.botium.ai/wp-content/uploads/2020/03/logo.png"
   },
   "buttons": [
     { "text": "First Button" },
     { "text": "Second Button" }
   ],
   "media": …,
   "forms": …,
   "cards": …,
 }
]

A card can have the following fields:

  • Text: The Title
  • Subtext: The Subtitle
  • Content: The main content as Text
  • Image: External link. Uri stored in mediaUri field
  • Buttons: Buttons of the card (stored in text, and payload fields)
  • Media: Media of the card (audio, video)
    Example:
    [
 {
   "mediaUri": "https://www.botium.ai/wp-content/uploads/2020/03/hello.wav",
   "altText": "hello",
   "mimeType": "audio/wav"
 }
]
  • Forms: Same structure as the main "forms" field
  • sourceData: Alternative to the "forms" field, to specify a form in AdaptiveCard format.
    Example 1:
    {
 "contentType": "application/vnd.microsoft.card.adaptive",
 "content": {
   "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
   "type": "AdaptiveCard",
   "version": "1.0",
   "body": [
     {
       "type": "TextBlock",
       "text": "Hello world!"
     }
   ]
 }
}
    Example 2:
    {
 "type": "AdaptiveCard",
 "body": [
   {
     "type": "TextBlock",
     "text": "Hello world!"
   }
 ]
}
  • cards: Subcards with the same structure as the main card

Other Fields

  • Sender: It is always "bot" in case of a Botium Bot Message
  • convoStepIndex: The current conversation step in the test case
  • nlp: Some chatbot providers are revealing information about the NLP engine, like the predicted intent. It is possible to add that information to the Botium Bot Message. NLP information is required to use NLP Asserters.

    There are many fields there. Rule of thumb is to fill as many as possible.

    Example:
    {
 "intent": {
   "name": "intent name",
   "confidence": 0.9999198913574219,
   "incomprehension": true,
   "intents": [
     {
       "name": "intent name",
       "confidence": 0.9999198913574219
     },
     {
       "name": "second intent name",
       "confidence": 0.24462083876132967
     }
   ]
 },
 "entities": [
   {
     "name": "genre",
     "value": "jazz",
     "confidence": 1
   },
   {
     "name": "appliance",
     "value": "music",
     "confidence": 1
   }
 ]
}

    The nlp field can have the following subfields:

    • intent.name: The name of the intent
    • intent.confidence: The confidence (between 0 and 1, including both)
    • intent.incomprehension: Some chatbot providers return a special intent for user examples it does not understand, like ‘none’. Those intents can be marked with this flag in order to get better results in Botium Coach
    • intent.intents: List of the alternative intents
    • entities.name: The name of the entity
    • entities.value: Value of the entity
    • entities.confidence: Confidence score of the entity

Was this article helpful?

0 out of 0 found this helpful