Third Party Bot Integration Guide

Summary

Bot Integration Structure Diagram

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

• POST /chatbotSessions - Create a new Chatbot Session
• POST /chatbotSession/{id}/interactions - Send a Chatbot Input and get a Chatbot Output
  See API Description for all interface definitions
  Click Data Struct to view key data structure definitions

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
   

API Description

ChatbotSession

• POST /chatbotSessions - Create a new Chatbot Session
• DELETE /chatbotSessions/{SessionId} - Delete the Chatbot Session

ChatbotInteraction

• POST /chatbotSession/{id}/interactions - Send a Chatbot Input and get a Chatbot Output

Endpoints

Create A New Chatbot Session

POST /chatbotSessions

Parameters

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

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:

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

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

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:

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

• ChatbotSession A ChatbotSession means a Session between the user and the chatbot
  • ChatbotInteraction One ChatbotInteraction means one user input and one Chatbot output
    • ChatbotInput One User Input
    • ChatbotOutput One Chatbot Output
      • ChatbotResponse One Chatbot output consists of multiple ChatbotResponse

CreateChatbotSessionRequest Object

CreateChatbotSessionResponse Object

InteractionRequest Object

InteractionResponse Object

ChatbotInput Object

InputText Object

InputLocation Object

InputOption Object

InputForm Object

FieldValue Object

VariableValue Object

ChatbotOutput Object

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

GeneralResponse Object

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

OutputText Object

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

TextLink Object

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

OutputQuickReply Object

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

OutputImage Object

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

OutputVideo Object

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

OutputLocation Object

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

OutputTransferChat Object

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

OutputAudio Object

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

OutputEndCall Object

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

agentid can obtain from there

departmentid can obtain from there

OutputForm Object

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

ChatbotActionSendFormField Object

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

Option Object

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

SessionVisitorInfo Object