Bot Message API

  • Updated on Mar 21, 2024
  • Published on Mar 11, 2022
  • 5 minute(s) read
Prev Next

Summary

  • Chatbot Message API. Use this API to send messages to Comm100 Live Chat channel while bot chatting

Only work in Comm100 Live Chat Channel

- session

Authentication

API_key Authentication

For each method call, you must use your email and API_KEY.Authentication to the API is done via HTTP Basic Auth. Provide your email as the basic auth username and API_KEY as the password. You must authenticate for API requests.

Session

  • POST /api/v3/bot/sessions/{sessionId}:sendMessage - Send Message

Related Object Json Format

ChatbotMessage

ChatbotMessage is represented as simple flat json objects with the following keys:

Name Type Mandatory Description
type enum yes it is a enum value with options: text,image,video, quickreply, button, intent.
content object yes response's content.
when type is text, it represents TextResponse;
when type is image,it represents ImageResponse;
when type is video, it represents VideoResponse;
when type is quickreply, it represents QuickReplyResponse;
when type is button, it represents ButtonResponse;
when type is intent, it represents IntentId or intent name;
disableChatInputArea bool no default value is false
delayTime decimal 1 how many seconds delay to show

TextResponse

TextResponse is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
message string yes message of the response
links array of link yes links in the text

Link

Link is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
type enum yes it is an enum value with options: hyperlink
startPosition int yes start index of text which contains link info
endPosition int yes end index of text which contains link info
url string no url of the web resource,including web forms,articles,images,video,etc. When the type is hyperlink, it is mandatory, otherwise not
ifPushPage bool no auto open url in the side window
openIn enum no it is an enum value with options: currentWindow,sideWindow and newWindow. This field defined the way that webpage will be opened.

ImageResponse

ImageResponse is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
description string yes description of the image, it will be displayed as the alternative text of the image
url string yes url of the image

VideoResponse

VideoResponse is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
url string yes url of the video

QuickReplyResponse

QuickReplyResponse is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
message string yes message of the response
items array of QuickReplyItem yes

QuickReplyItem

QuickReplyItem is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
type enum yes it is an enum value with options: goToIntent, contactAgent and text
text string yes text on quick reply
intentId GUID no id of the intent which current quickreply point to. When the type is goToIntent, it is mandatory, otherwise not
intentName string no name of the intent which current quickreply point to. It will only take effect if intentId is empty or not set.

ButtonResponse

ButtonResponse is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
message string yes message of the response
items array of ButtonItem yes

ButtonItem

ButtonItem is represented as simple flat JSON objects with the following keys:

Name Type Mandatory Description
type enum yes it is an enum value with options: hyperlink,webview and goToIntent
text string yes text on button
url string no url of the web resource,including web forms,articles,images,video,etc. When the type is hyperlink or webview, it is mandatory, otherwise not
intentId GUID no id of the intent which current button point to. When the type is goToIntent, it is mandatory, otherwise not
intentName string no name of the intent which current button point to. It will only take effect if intentId is empty or not set.
openIn enum no it is an enum value with options: currentWindow,sideWindow and newWindow. This field defined the way that webpage will be opened. When the type is hyperlink, it is mandatory, otherwise not
webviewOpenStyle enum no it is an enum value with options: compact, tall and full. This field defined the way that webview will be opened. When the type is webview, it is mandatory, otherwise not

Endpoints

Send Message

POST /api/v3/bot/sessions/{sessionId}:sendMessage

Parameters

Path parameters

Name Type Required Description
sessionId Guid yes id of the chat

Query String

Name Type Required Description
siteId int yes id of the site

Request body

The request body contains data with the follow structure:

Name Type Required Default Description
botId Guid yes id of the chatbot
visitorId Guid yes id of the visitor
intentId Guid no id of the intent
messages ChatbotMessage[] yes max 10 messages in the list and only 1 quickreply type message in the list

example:

  {
    "botId": "44f88d68-92e6-4487-a2e8-8234fc9d1f48",
    "visitorId": "a9928d68-92e6-4487-a2e8-8234fc9d1f48",
    "messages": [
        {
            "type": "text",
            "content": {
                "message": "this is a plain message"
            },
            "disableChatInputArea": true
        },
    ]
  }

Response

HTTP/1.1 204 No Content

Example

Using curl

curl -H "Authorization: Basic test@comm100.com:e07cce30b1b145e99049bf201f302239"
-H "Content-Type: application/json" -d '{
    "botId": "44f88d68-92e6-4487-a2e8-8234fc9d1f48",
    "visitorId": "a9928d68-92e6-4487-a2e8-8234fc9d1f48",
    "messages": [
        {
            "type": "text",
            "content": {
                "message": "this is a plain message"
            },
            "disableChatInputArea": true
        },
    ]
  }' -X POST https://api2.comm100.io/botapi/api/v3/bot/sessions/f9928d68-92e6-4487-a2e8-8234fc9d1f48:sendMessage?siteId=10000

Response

  HTTP/1.1 204 No Content
  Content-Type:  application/json

ChatbotMessage List Sample Json

 [
      {
          "type": "text",
          "content": {
              "message": "this is a plain message"
          },
          "disableChatInputArea": true
      },
      {
          "type": "text",
          "content": {
              "message": "this is a web link message",
              "link": [{
                  "type": "hypelink",// hypelink
                  "startPosition": 10,
                  "endPosition": 17,
                  "ifPushPage": true,
                  "url": "www.test.com",
                  "openIn": "sideWindow"// currentWindow, sideWindow or newWindow.
              }]
          },
          "disableChatInputArea": true
      },        
      {
          "type": "image",
          "content": {
              "description": "description of the image",
              "url": "www.test.com/test-image.jpg"
          },
          "disableChatInputArea": true
      },
      {
          "type": "video",
          "content": {
              "url": "www.test.com/test-video.jpg"
          },
          "disableChatInputArea": true
      },        
      {
          "type": "button",
          "content": {
              "message": "this is a button response",
              "items": [
                  {
                      "type": "goToIntent",// goToIntent, hyperlink or webview.
                      "text": "click to trigger test-intent-name",
                      "intentId": "00000000-0000-0000-0000-000000001111"
                  },
                  {
                      "type": "hyperlink",
                      "text": "click to open this url in web page",
                      "url": "www.test.com",
                      "openIn": "currentWindow"
                  },
                  {
                      "type": "webview",
                      "text": "click to open this url in web view",
                      "url": "www.test.com",
                      "webviewOpenStyle": "full"
                  }
              ]
          },
          "disableChatInputArea": true
      }, {
          "type": "quickreply",
          "content": {
              "message": "this is a quick reply response",
              "items": [
                  {
                      "type": "goToIntent",// goToIntent, contactAgent or text.
                      "text": "click to trigger test-intent-name",
                      "intentId": "00000000-0000-0000-0000-000000001111"
                  },
                  {
                      "type": "goToIntent",// goToIntent, contactAgent or text.
                      "text": "Go to main menu",
                      "intentName": "main menu"
                  },
                  {
                      "type": "contactAgent",
                      "text": "click to contact agent"
                  }
              ]
          },
          "disableChatInputArea": true
      },
  ]
Copyright © 2022 Comm100 Network Corporation. All Rights Reserved.