Understanding the Certainly WebSocket

The Certainly WebSocket allows you to connect your custom apps to a Certainly chatbot without the need for the user to interact with the bot through the chat widget.

In this article, we'll look at how to connect through the WebSocket, how to send messages to a chatbot via the WebSocket, and what responses we can expect from a bot.

• What is a WebSocket?
• Connecting to the Certainly WebSocket
• Sending user messages via the Certainly WebSocket
• Bot responses through the Certainly WebSocket
• Types of actions available through the Websocket messages

What is a WebSocket?

The WebSocket technology makes it possible to open a two-way interactive communication session between a user's browser and a server. With this API, users send messages to a server and receive event-driven responses without having to poll the server for a reply.

For more technical information on WebSockets and their functioning, please consult the MDN Web Docs resource.

Connecting to the Certainly WebSocket

In order to connect to the Certainly WebSocket, you must make a GET request to the following endpoint:

wss://app.certainly.io/webbot/api/webchat/ENTER_BOT_DEPLOYMENT_ID_HERE/

Make sure to substitute your bot's unique Bot Deployment ID in the code above.

Once the WebSocket connection has been successfully established, we will be able to communicate back and forth with the bot straight from the WebSocket, without the need for an open chat.

Sending user messages via the Certainly WebSocket

The payload for a visitor message follows this structure:

{
   "message": {
   "from": "human",
   "user_profile": {},
   "ref": null,
   "user_id": "webbot:xxxxxx-xxxxxx-xxxxxx-xxxxxx-xxxxxx",
   "timestamp": 1649659256,
   "attachments": [],
   "id": "xxxxxxxxxx",
   "actions": [
     {
       "type": "text",
       "text": "hello"
     }
   ]
 }
}

Now we'll break down this structure and dive deeper into the different configuration options of the user message object.

User message object breakdown

We'll cover all the different types of actions in another section below.

Bot responses through the Certainly WebSocket

Bot responses through the WebSocket will also be sent inside a JSON payload. Here, you can take a look at the main structure of the bot response object:

{
  "error":null,
  "message":{
    "bot_module":{
      "id":xxxxxxxxxx,
      "name":"Starting module",
      "group_colour":null,
      "kpi_tags":[
         {
          "label":"Start",
          "id":1,
          "colour":"#B50000"
         }
      ]
    },
    "connections":{
    "id_message_evaluate":"",
    "reply_to_module_id":null,
    "data":[]
    },
  "from":"bot",
  "actions":[
    {
    "type":"text",
    "text":"xxxxxxxxxx"
    }
  ],
  "id":XXXXXX,
  "conversation_id":xxxxxxxxxx
  }
}

Bot response object breakdown

We'll cover all the different types of actions in the next section.

Types of actions available through the Websocket messages

Our bots are capable of providing responses such as regular text messages or cards with information and URLs, sending audio, video, or images, and more. End users can also interact with the bot in different ways. We can configure the WebSocket to perform all these functionalities through the "actions" object inside both the user messages and bot responses.

Now we'll explore the different action types available, their main differentiating configuration options, and some examples.

• Text
• Wait
• Choice
• Cards
• Metadata
• Media files

Text

This is the most basic action type and consists of simple text messages that are shown to the user. 

As an example, we can have this bot response in which the bot sends the message "Hi! Welcome to Certainly" to the user:

{
  "error":null,
  "message":{
    "bot_module":{
    "id":xxxxxxxxxx,
    "name":"Starting module",
  },
  "from":"bot",
  "actions":[
  {
    "type":"text",
    "text":"Hi! Welcome to Certainly"
  }
  ]
  "cvars":{
  },
  "id":xxxxxxxxxx,
  "conversation_id":xxxxxxxxxx
  }
}

By setting the actions array with an object with key "type" and value "text", you can then add a second key named "text". The value for this key must contain a string.

To configure the text action, we need to set the action with an object containing the following configuration:

• type: This key must be set with the value "text" so that the messages are rendered.
• text: This key contains the string that will be printed by the bot or typed by the user.

Wait

This allows us to set delays between different actions inside the same bot response. In the next example, the bot is sending several messages inside the same response. The different messages are separated by a 1000-millisecond delay.

{
  "error":null,
  "message":{
  "bot_module":{
    "id":xxxxxxxxxx,
    "name":"Starting module",
  },
  "from":"bot",
  "actions":[
  {
    "type":"text",
    "text":"Hi! Welcome to Certainly"
  }
  {
    "type":"wait",
    "wait":1000
  },
  {
    "type":"text",
    "text":"Here at Certainly, we make it easy for you to build your own AI-based chatbot"
  }
  ]
  "cvars":{
  },
  "id":xxxxxxxxxx,
  "conversation_id":xxxxxxxxxx
  }
 }

To configure the wait action, we need to set the action with an object containing the following configuration:

• type: Setting this key with the value "wait" allows you to configure delays between messages inside the same response.
• wait: The value for this key specifies the delay (In milliseconds) between the different messages.

Choice

Through this action, the bot is capable of offering the user several recommended responses. The user can then quickly choose between them without needing to type inside the chat.

{
  "error": null,
  "message": [
  {
      "from": "bot",
      "bot_module": {
        "kpi_tags": [],
        "id": xxxxxxxxxx
    },
    "actions": [
    {
      "text": "I'm a multiple choice question",
      "type": "choice",
      "options_type": "options",
      "options": ["Option1", "Option2", "Option3", "Option4"]
    }
    ]
  }
  ]
}

To configure the choice action, we need to set the action with an object containing the following configuration:

• type: To provide the user with selectable recommended responses, this key must be set with the value "choice".
• text: Though it is not mandatory, you can set a message that helps give context to the customer.
• options_type: This key is set either with value "options" or "suggested_replies".
• options: An array of strings for each of the different options provided to the user.

Cards

This action is used to render cards through the WebSocket. A bot response through the WebSocket in which the bot is rendering two different Dynamic Cards will look similar to this:

{  
  "error": null,
  "message": [
    {
       "bot_module": {
       "kpi_tags": [],
       "id": xxxxxxxxxx,
    },
    "actions": [
      {
         "cards": [
           {
             "title": "Card1 title",
             "text": "Card1 subtitle",
             "is_shareable": False,
             "image_destination_url": "https://someurl.com",
             "image_source_url": "https://someurl.com/image.png", # noqa
             "buttons": [],
           },
           {
             "title": "Card2 title",
             "text": "Card2 subtitle",
             "is_shareable": False,
             "image_destination_url": "https://someotherurl.com", # noqa
             "image_source_url": "https://someotherurl.com/image.png", # noqa
             "buttons": [],
           }
         ],
         "type": "card"
       }
  ],
  "from": "bot"
} 

To configure the card action, we need to set the action with an object containing the following configuration:

• type: The type for this specific action must be set to "card".
• cards: This is an array in which we have a separate object for each card rendered. These objects contain:
  • title: A descriptive title for the given card.
  • text: This can provide additional context regarding the card.
  • is_shareable: This can take two different values ("true" or "false").
  • image_destination_url: The value of this key contains the URL of the destination image.
  • image_source_url: The value of this key contains the URL of the source image.
  • buttons: Represents buttons present in the card that will perform specific actions when clicked.

Metadata

This action is used to send Custom Variables through the bot. An example of a bot sending Custom Variables through this type of action looks like this:

{
  "message": {
    "from": "human",
    "user_profile": {},
    "ref": null,
    "id": xxxxxxxxxx,
    "actions":[
      {
        "type":"cvar",
        "priority":0,
        "data":{
          "key":"test",
          "value":{
            "fixed_value":"2",
            "type":0
          }
        }
      }
    ]
  }
}

To configure the CVar action, we need to set the action with an object containing the following configuration:

• type: The type for this specific action must be set as "cvar".
• priority: You must set a priority for this action. It is recommended to set this to "0" for external WebSocket messages.
• data: This is further subdivided into two more pairs of key-value combinations:
  • key: The name of the variable you want to store.
  • value: The value set for the variable.

Media files

The WebSocket allows us to display media content such as audio, video, or images. You can see an example here:

{
  "message": [
    {
      "from": "bot",
      "bot_module": {
        "kpi_tags": [],
        "id": xxxxxxxxxx
      },
    "actions": [
      {
        "type": "image",
        "url": "http://cd.textfiles.com/mmplatinum/IMAGES/BMP/ASTRO2.BMP" 
      }
    ]
    }
  ]
}

To configure the audio/video/image action, we need to set the action with an object containing the following configuration:

• type: Depending on the content being shared, this key will take the value "audio", "video", or "image".
• url: The URL of the content being rendered.