Third Party Bot Integration Guide
  • 08 Feb 2023
  • 6 Minutes to read
  • Dark
    Light

Third Party Bot Integration Guide

  • Dark
    Light

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:

Name Type Required Default Description
chatbotId Guid yes The unique id of the bot
channel string yes The channel of the bot
visitor SessionVisitorInfo no

example:

  {
    "chatbotId": "f9928d68-92e6-4487-a2e8-8234fc9d1f48",
    "channel": "Live Chat",
    "visitor": {
        "name":"Kart",
        "email":"kart@yahoo.com",
        "phone":"123-4355-212",
      }
    }
  }

Response

The Response body contains data with the following structure:

Name Type Description
sessionId string The unique id of the session
content GeneralResponse[]

Example

Using curl

curl -H "Content-Type: application/json" -d '{
    "chatbotId": "f9928d68-92e6-4487-a2e8-8234fc9d1f48", 
    "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

Name Type Required Description
chatbotSessionId string yes the 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":"i want to buy NBN"
      }
    }
  }

.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"
      }
    }
  }' -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

Name Type Default Description
chatbotId Guid chatbotId
channel string including Live Chat,Facebook Messager,Twitter Direct Message,WeChat,WhatsApp,IVR,SMS
visitor SessionVisitorInfo

CreateChatbotSessionResponse Object

Name Type Default Description
sessionId string sessionId
content GeneralResponse[]

InteractionRequest Object

Name Type Default Description
input ChatbotInput

InteractionResponse Object

Name Type Default Description
output ChatbotOutput

ChatbotInput Object

Name Type Default Description
type String type of the response,includingtext,location,option,form
content object InputText, InputLocation, InputOption,InputForm

InputText Object

Name Type Default Description
text String

InputLocation Object

Name Type Default Description
location String the longitude and latitude of the location, e.g. "-39.900000,116.300000"
action string submit, cancel

InputOption Object

Name Type Default Description
optionId String optionId

InputForm Object

Name Type Default Description
formValues FieldValue[] an array of FieldValue
action string submit, cancel

FieldValue Object

Name Type Default Description
name string the name of a field in a form.
value string the value of a field.

VariableValue Object

Name Type Default Description
name string the name of a variable in a form.
value string the value of a variable.

ChatbotOutput Object

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

Name Type Default Description
id Guid the unique id of the response
content GeneralResponse[]

GeneralResponse Object

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

Name Type Default Description
type string type of the response,including Text,QuickReplyImageVideoAuthentication,Location,VariableData,Form,TransferChat
content object response'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; when type is OutputAudio, it represents OutputAudio;when type is OutputEndCall, it represents OutputEndCall;
delayTime decimal 1 how many seconds delay to show

OutputText Object

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

Name Type Default Description
message string string
Links TextLink[]

TextLink Object

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

Name Type Default Description
buttonText String
url String
type String webPage,webview
openStyle String full,tall,compact
openIn String newWindow, sideWindow,currentWindow
order int

OutputQuickReply Object

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

Name Type Default Description
message string string
options option[]
isForce bool must select and can not input text

OutputImage Object

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

Name Type Default Description
imageUrl string string
message string string

OutputVideo Object

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

Name Type Default Description
videoUrl string string
message string string

OutputLocation Object

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

Name Type Default Description
buttonText string string
isForce bool must location and can not input text
message string string

OutputTransferChat Object

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

Name Type Default Description
transferTo Guid agentid when type is transferToAgent ,departmentid when type is transferToDepartment
type string type:transferToAgent,transferToDepartment,transferRoutingRules
messageWhenAgentOffline string Message when agent is offline

OutputAudio Object

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

Name Type Default Description
audioPath String String

OutputEndCall Object

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

Name Type Default Description

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:

Name Type Default Description
message string A separate message which is sent before the form is sent.
title string the title of that form
isConfirmationRequired bool whether visitor needs to click confirm before the form is submitted.
fields ChatbotActionSendFormField[] an array of ChatbotActionSendFormField
submitButtonText string
cancelButtonText string
confirmButtonText string
isforce string

ChatbotActionSendFormField Object

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

Name Type Default Description
type string enums: text ,textArea,radio ,checkBox ,dropDownList ,checkBoxList,email type refers to the different kinds of fields which can be used in a form.
name string Name of the form field.
value string Value of the field
isRequired bool Whether the field is required or not
options string[] an array of of string when the fieldType is radio ,dropDownList ,checkBoxList
order integer Must be greater than or equal 0, ascending sort
variableName string

Option Object

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

Name Type Default Description
optionId Guid
order int
text String
type String text type of the option,including TriggerAnIntent,ContactAnAgentText

SessionVisitorInfo Object

Name Type Default Description
name string
email string
phone string
state/province string
country/region string
city string
ip string
email string
currentPageURL string
searchEngine string
searchKeywords string
longitude number
latitude number
pageViews integer
browser integer
chats integer
company string
currentBrowsing string
department string
firstVisitTime time
flashVersion string
keywords string
landingPage string
language string
operatingSystem string
productService string
ticketId string
referrerUrl string
screenResolution string
searchEngine string
state string
status integer
timeZone string
visitTime time
visits integer
ssoId integer
chatRequestingPageUrl integer
campaignId string
channelAccountId string

Was this article helpful?