Third Party Bot Integration Guide
  • 12 Jan 2024
  • 8 Minutes to read
  • Dark
    Light

Third Party Bot Integration Guide

  • Dark
    Light

Article Summary

Summary

Bot Integration Structure Diagram

image

Integration Steps

To integrate your Chatbot with Comm100 Platform, you only need to do the following two steps:

1. Building Your Bot Adapter Service

As shown in the diagram, You need to establish your own Chatbot Adapter, which connects to your BOT Engine service and implements the interfaces in this API documents.
You can first implement the following two important interfaces and start chatting

2. Creating a new Comm100 Chatbot and fill in your adapter service base URI

Create a new Chatbot in the Comm100 Control panel and configure it as follows

  1. Fill in the Bot name
  2. Select "Third Party Engine" as the bot Engine
  3. Fill in your adapter root URI in the "Webhook target URL" input box ,The port number of the URL needs to be 80.
  4. Select the Comm100 Live Chat channel
    image

API Description

ChatbotSession

ChatbotInteraction

Endpoints

Create A New Chatbot Session

POST /chatbotSessions

Parameters

Request Body
The request body contains data with the following structure:

NameTypeRequiredDefaultDescription
chatbotIdGuidyesThe unique id of the bot
channelstringyesThe channel of the bot
chatIdGuidnoThe chat id from Comm100
visitorSessionVisitorInfono

example:

 {
    "chatbotId": "6ce62c7c-211c-4989-b87f-ef9ac84a0409",
    "channel": "Live Chat",
    "chatId": "9537477a-9437-4382-8f4a-f598eedd396a",
    "visitor": {
        "visitorGuid": "18ca8c7b-82ea-403d-9d9d-12cc63cc84d4",
        "longitude": 0,
        "latitude": 0,
        "pageViews": 1,
        "browser": "Google Chrome 112.0.0.0",
        "chats": 5,
        "city": "",
        "company": "",
        "country": "Hong Kong",
        "currentBrowsing": "https://testing.comm100dev.io",
        "customFields": [
            {
                "name": "aname",
                "value": "aaaaaa"
            }
        ],
        "customVariables": [
            {
                "name": "host",
                "value": "testing.comm100dev.io"
            }
        ],
        "department": "00000001-0000-0000-0000-000000000001",
        "email": "xxx@comm100.com",
        "firstVisitTime": "2023-04-26T09:28:05.437Z",
        "flashVersion": "",
        "ip": "0.0.0.0",
        "keywords": "",
        "landingPage": "https://testing.comm100dev.io",
        "language": "en-US",
        "name": "xxx",
        "operatingSystem": "Windows 10",
        "phone": "",
        "productService": "",
        "ticketId": "",
        "referrerUrl": "https://testing.comm100dev.io",
        "screenResolution": "1536x864",
        "searchEngine": "",
        "state": "",
        "status": 2,
        "timeZone": "GMT +08:00",
        "visitTime": "2023-04-27T09:49:38.7068514Z",
        "visits": 3,
        "ssoId": "",
        "chatRequestingPageUrl": "https://testing.comm100dev.io",
        "segments": [],
        "campaignId": "6efb0be2-8fac-4f69-8267-ee9e845a27c2",
        "channelAccountId": "00000000-0000-0000-0000-000000000000",
        "ticketVariables": [],
        "timeOnWebSite": 450,
        "timeOnCurrentPage": 450,
        "isAgentOnline": true
    }
}

Response

The Response body contains data with the following structure:

NameTypeDescription
sessionIdstringThe unique id of the session
contentGeneralResponse[]

Example

Using curl

curl -H "Content-Type: application/json" -d '{
    "chatbotId": "6ce62c7c-211c-4989-b87f-ef9ac84a0409",
    "channel": "Live Chat",
    "chatId": "9537477a-9437-4382-8f4a-f598eedd396a",
    "visitor": {
      "name":"Kart",
      "email":"kart@yahoo.com",
      "phone":"123-4355-212",
    }
  }' -X POST https://domain.comm100.com/api/v4/chatbotSessions

.net code example
image

Response

  HTTP/1.1 200 OK
  Content-Type:  application/json

{
    "sessionId": "f9928d68-92e6-4487-a2e8-8234fc9d1f48",
    "content": [
        {
            "type": "text",
            "content": {
                "links": [
                    {
                        "buttonText": "ok",
                        "url": "http://baidu.com",
                        "type": "intent",
                        "openStyle": "tail",
                        "openIn": "sideWindow",
                        "order": 1
                    }
                ],
                "message": "Hi there! I'm a chatbot, here to help answer your questions."
            },
            "delaytime":1
        }
    ]
}

Delete The Chatbot Session

DELETE /chatbotSessions/{ChatbotSessionId}

Parameters

Path parameters

NameTypeRequiredDescription
chatbotSessionIdstringyesthe unique id of the Chatbot Session

Response

This method does not specify any sample responses.

Example

Using curl

curl -X DELETE https://domain.comm100.com/api/v4/chatbotSessions/a9928d68-92e6-4487-a2e8-8234fc9d1f48

Response Example

  HTTP/1.1 200 OK

Create a Chatbot Interaction

POST /chatbotSession/{chatbotSessionId}/interactions

Parameters

Request body

The request body is: InteractionRequest Object

example:

  {
    "input": {
        "type": "text",
        "content": {
            "text": "hi"
        }
    },
    "chatbotId": "6ce62c7c-211c-4989-b87f-ef9ac84a0409",
    "channel": "Live Chat",
    "chatId": "9537477a-9437-4382-8f4a-f598eedd396a",
    "visitor": {
        "visitorGuid": "18ca8c7b-82ea-403d-9d9d-12cc63cc84d4",
        "longitude": 0,
        "latitude": 0,
        "pageViews": 1,
        "browser": "Google Chrome 112.0.0.0",
        "chats": 5,
        "city": "",
        "company": "",
        "country": "Hong Kong",
        "currentBrowsing": "https://testing.comm100dev.io",
        "customFields": [
            {
                "name": "aname",
                "value": "aaaaaa"
            }
        ],
        "customVariables": [
            {
                "name": "host",
                "value": "testing.comm100dev.io"
            }
        ],
        "department": "00000001-0000-0000-0000-000000000001",
        "email": "xxx@comm100.com",
        "firstVisitTime": "2023-04-26T09:28:05.437Z",
        "flashVersion": "",
        "ip": "0.0.0.0",
        "keywords": "",
        "landingPage": "https://testing.comm100dev.io",
        "language": "en-US",
        "name": "xxx",
        "operatingSystem": "Windows 10",
        "phone": "",
        "productService": "",
        "ticketId": "",
        "referrerUrl": "https://testing.comm100dev.io",
        "screenResolution": "1536x864",
        "searchEngine": "",
        "state": "",
        "status": 2,
        "timeZone": "GMT +08:00",
        "visitTime": "2023-04-27T09:49:38.7068514Z",
        "visits": 3,
        "ssoId": "",
        "chatRequestingPageUrl": "https://testing.comm100dev.io",
        "segments": [],
        "campaignId": "6efb0be2-8fac-4f69-8267-ee9e845a27c2",
        "channelAccountId": "00000000-0000-0000-0000-000000000000",
        "ticketVariables": [],
        "timeOnWebSite": 450,
        "timeOnCurrentPage": 450,
        "isAgentOnline": true
    }
}

.net code example:
image

Response

the response is: InteractionResponse Object

Example

Using curl

curl -H "Content-Type: application/json" -d '{
    "input":{
      "type":"text",
      "content":{
        "text":"i want to buy NBN"
      }
    },
    "chatbotId": "6ce62c7c-211c-4989-b87f-ef9ac84a0409",
    "channel": "Live Chat",
    "chatId": "9537477a-9437-4382-8f4a-f598eedd396a",
    "visitor": {
      "name":"Kart",
      "email":"kart@yahoo.com",
      "phone":"123-4355-212",
    }
  }' -X POST https://domain.comm100.com/api/v4/chatbotSessions/f9928d68-92e6-4487-a2e8-8234fc9d1f48/interactions

Response

  HTTP/1.1 200 OK
  Content-Type:  application/json

  { 
    "output":{
          "id":"d3f5b968-ad51-42af-b759-64c0afc40b84",
          "content":[
              {
                "type":"text",
                "content": {
                    "links": [{
                      "buttonText":"ok",
                      "url":"http://baidu.com",
                      "type":"intent",
                      "openStyle":"tail",
                      "openIn":"sideWindow",
                      "order":1,
                    }],
                    "message": "Hi there! I'm a chatbot, here to help answer your questions.",                        
              },
                "delaytime":1
              }
          ]
    }   
  }

Data Struct

CreateChatbotSessionRequest Object

NameTypeDefaultDescription
chatbotIdGuidchatbotId
channelstringincluding Live Chat,Facebook Messager,Twitter Direct Message,WeChat,WhatsApp,IVR,SMS
chatIdGuidThe chat id from Comm100
visitorSessionVisitorInfo

CreateChatbotSessionResponse Object

NameTypeDefaultDescription
sessionIdstringsessionId
contentGeneralResponse[]

InteractionRequest Object

NameTypeDefaultDescription
inputChatbotInput
chatbotIdGuidchatbotId
channelstringincluding Live Chat,Facebook Messager,Twitter Direct Message,WeChat,WhatsApp,IVR,SMS
chatIdGuidThe chat id from Comm100
visitorSessionVisitorInfo

InteractionResponse Object

NameTypeDefaultDescription
outputChatbotOutput

ChatbotInput Object

NameTypeDefaultDescription
typeStringtype of the response,includingtext,location,option,form
contentobjectInputText, InputLocation, InputOption,InputForm

InputText Object

NameTypeDefaultDescription
textString

InputLocation Object

NameTypeDefaultDescription
locationStringthe longitude and latitude of the location, e.g. "-39.900000,116.300000"
actionstringsubmit, cancel

InputOption Object

NameTypeDefaultDescription
optionIdStringoptionId

InputForm Object

NameTypeDefaultDescription
formValuesFieldValue[]an array of FieldValue
actionstringsubmit, cancel

FieldValue Object

NameTypeDefaultDescription
namestringthe name of a field in a form.
valuestringthe value of a field.

VariableValue Object

NameTypeDefaultDescription
namestringthe name of a variable in a form.
valuestringthe value of a variable.

ChatbotOutput Object

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

NameTypeDefaultDescription
idGuidthe unique id of the response
contentGeneralResponse[]

GeneralResponse Object

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

NameTypeDefaultDescription
typestringtype of the response,including Text,QuickReplyImageVideoLocation,Form,TransferChat,LeaveChat
contentobjectresponse's content. when type is Text, it represents OutputText; when type is QuickReply,it represents OutputQuickReply;when type is Image,it represents OutputImage;when type is Video,it represents OutputVideo; when type is Location, it represents OutputLocation;when type is Form, it represents OutputForm;when type is TransferChat, it represents OutputTransferChat;
delayTimedecimal1how many seconds delay to show

OutputText Object

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

NameTypeDefaultDescription
messagestringstring
LinksTextLink[]

TextLink Object

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

NameTypeDefaultDescription
buttonTextString
urlString
typeStringwebPage,webview
openStyleStringfull,tall,compact
openInStringnewWindow, sideWindow,currentWindow
orderint

OutputQuickReply Object

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

NameTypeDefaultDescription
messagestringstring
optionsoption[]
isForceboolmust select and can not input text

OutputImage Object

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

NameTypeDefaultDescription
imageUrlstringstring
messagestringstring

OutputVideo Object

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

NameTypeDefaultDescription
videoUrlstringstring
messagestringstring

OutputLocation Object

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

NameTypeDefaultDescription
buttonTextstringstring
isForceboolmust location and can not input text
messagestringstring

OutputTransferChat Object

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

NameTypeDefaultDescription
messagestringMessage before starting to transfer
transferToGuidagentid when type is transferToAgent ,departmentid when type is transferToDepartment
typestringtype:transferToAgent,transferToDepartment,transferRoutingRules
messageWhenAgentOfflinestringMessage when agent is offline

OutputAudio Object

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

NameTypeDefaultDescription
audioPathStringString

OutputEndCall Object

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

NameTypeDefaultDescription

agentid can obtain from there

ac0859808d9d39f528d6863e9d46a2d

departmentid can obtain from there

image

OutputForm Object

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

NameTypeDefaultDescription
messagestringA separate message which is sent before the form is sent.
titlestringthe title of that form
isConfirmationRequiredboolwhether visitor needs to click confirm before the form is submitted.
fieldsChatbotActionSendFormField[]an array of ChatbotActionSendFormField
submitButtonTextstring
cancelButtonTextstring
confirmButtonTextstring
isforcestring

ChatbotActionSendFormField Object

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

NameTypeDefaultDescription
typestringenums: text ,textArea,radio ,checkBox ,dropDownList ,checkBoxList,email type refers to the different kinds of fields which can be used in a form.
namestringName of the form field.
valuestringValue of the field
isRequiredboolWhether the field is required or not
optionsstring[]an array of of string when the fieldType is radio ,dropDownList ,checkBoxList
orderintegerMust be greater than or equal 0, ascending sort
variableNamestring

Option Object

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

NameTypeDefaultDescription
optionIdGuid
orderint
textString
typeStringtexttype of the option,including TriggerAnIntent,ContactAnAgentText

SessionVisitorInfo Object

NameTypeDefaultDescription
visitorGuidGuid
namestring
emailstring
phonestring
state/provincestring
country/regionstring
citystring
ipstring
emailstring
currentPageURLstring
searchEnginestring
searchKeywordsstring
longitudenumber
latitudenumber
pageViewsinteger
browserinteger
chatsinteger
companystring
currentBrowsingstring
departmentstring
firstVisitTimetime
flashVersionstring
keywordsstring
landingPagestring
languagestring
operatingSystemstring
productServicestring
ticketIdstring
referrerUrlstring
screenResolutionstring
searchEnginestring
statestring
statusinteger
timeZonestring
visitTimetime
visitsinteger
ssoIdinteger
chatRequestingPageUrlinteger
campaignIdstring
channelAccountIdstring
customFieldsFieldValue[]an array of FieldValue
customVariablesFieldValue[]an array of FieldValue

Was this article helpful?