--- title: "Third Party Bot Integration Guide" slug: "guides-bot-integration-third-party-bot-integration-guide" updated: 2024-01-12T09:02:29Z published: 2024-01-12T09:02:29Z canonical: "developer.comm100.com/guides-bot-integration-third-party-bot-integration-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://developer.comm100.com/llms.txt > Use this file to discover all available pages before exploring further. # Third Party Bot Integration Guide ## Summary ### Bot Integration Structure Diagram ![image](https://user-images.githubusercontent.com/8872646/146502833-661bd26b-2e35-4e71-88af-fea3f1a4a6f7.png) ### 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](/docs/guides-bot-integration-third-party-bot-integration-guide#create-a-new-chatbot-session) - `POST /chatbotSession/{id}/interactions` - [Send a Chatbot Input and get a Chatbot Output](/docs/guides-bot-integration-third-party-bot-integration-guide#create-a-chatbot-interaction) See [API Description](/docs/guides-bot-integration-third-party-bot-integration-guide#api-description) for all interface definitions Click [Data Struct](/docs/guides-bot-integration-third-party-bot-integration-guide#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 ![image](https://user-images.githubusercontent.com/8872646/146148035-2b0d215e-0064-45a2-bcd7-07cbd16356e5.png) ## API Description ### ChatbotSession - `POST /chatbotSessions` - [Create a new Chatbot Session](/docs/guides-bot-integration-third-party-bot-integration-guide#create-a-new-chatbot-session) - `DELETE /chatbotSessions/{SessionId}` - [Delete the Chatbot Session](/docs/guides-bot-integration-third-party-bot-integration-guide#delete-the-chatbot-session) ### ChatbotInteraction - `POST /chatbotSession/{id}/interactions` - [Send a Chatbot Input and get a Chatbot Output](/docs/guides-bot-integration-third-party-bot-integration-guide#create-a-chatbot-interaction) ## 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 | | `chatId` | Guid | no | | The chat id from Comm100 | | `visitor` | [SessionVisitorInfo](/docs/guides-bot-integration-third-party-bot-integration-guide#sessionvisitorinfo-object) | no | | | 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: | Name | Type | Description | | --- | --- | --- | | `sessionId` | string | The unique id of the session | | `content` | [GeneralResponse](/docs/guides-bot-integration-third-party-bot-integration-guide#generalresponse-object)[] | | #### 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](https://user-images.githubusercontent.com/8872646/153159849-198ff873-de2b-405c-b65b-aea100374a16.png) 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](/docs/guides-bot-integration-third-party-bot-integration-guide#interactionrequest-object) 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](https://user-images.githubusercontent.com/8872646/146140038-e9e1be33-ce9c-4b0f-8b4a-75d4cd63ff75.png) #### Response the response is: [InteractionResponse](/docs/guides-bot-integration-third-party-bot-integration-guide#interactionresponse-object) 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](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotsession) A ChatbotSession means a Session between the user and the chatbot - [ChatbotInteraction](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotinteraction) One ChatbotInteraction means one user input and one Chatbot output - [ChatbotInput](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotinput-object) One User Input - [ChatbotOutput](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotoutput-object) One Chatbot Output - [ChatbotResponse](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotresponse-object) One Chatbot output consists of multiple ChatbotResponse ### CreateChatbotSessionRequest Object | Name | Type | Default | Description | | --- | --- | --- | --- | | `chatbotId` | Guid | | chatbotId | | `channel` | string | | including `Live Chat`,`Facebook Messager`,`Twitter Direct Message`,`WeChat`,`WhatsApp`,`IVR`,`SMS` | | `chatId` | Guid | | The chat id from Comm100 | | `visitor` | [SessionVisitorInfo](/docs/guides-bot-integration-third-party-bot-integration-guide#sessionvisitorinfo-object) | | | ### CreateChatbotSessionResponse Object | Name | Type | Default | Description | | --- | --- | --- | --- | | `sessionId` | string | | sessionId | | `content` | [GeneralResponse](/docs/guides-bot-integration-third-party-bot-integration-guide#generalresponse-object)[] | | | ### InteractionRequest Object | Name | Type | Default | Description | | --- | --- | --- | --- | | `input` | [ChatbotInput](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotinput-object) | | | | `chatbotId` | Guid | | chatbotId | | `channel` | string | | including `Live Chat`,`Facebook Messager`,`Twitter Direct Message`,`WeChat`,`WhatsApp`,`IVR`,`SMS` | | `chatId` | Guid | | The chat id from Comm100 | | `visitor` | [SessionVisitorInfo](/docs/guides-bot-integration-third-party-bot-integration-guide#sessionvisitorinfo-object) | | | ### InteractionResponse Object | Name | Type | Default | Description | | --- | --- | --- | --- | | `output` | [ChatbotOutput](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotoutput-object) | | | ### ChatbotInput Object | Name | Type | Default | Description | | --- | --- | --- | --- | | `type` | String | | type of the response,including`text`,`location`,`option`,`form` | | `content` | object | | [InputText](/docs/guides-bot-integration-third-party-bot-integration-guide#inputtext-object), [InputLocation](/docs/guides-bot-integration-third-party-bot-integration-guide#inputlocation-object), [InputOption](/docs/guides-bot-integration-third-party-bot-integration-guide#inputoption-object),[InputForm](/docs/guides-bot-integration-third-party-bot-integration-guide#inputform-object) | ### 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](/docs/guides-bot-integration-third-party-bot-integration-guide#fieldvalue-object)[] | | an array of [FieldValue](/docs/guides-bot-integration-third-party-bot-integration-guide#fieldvalue-object) | | `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](/docs/guides-bot-integration-third-party-bot-integration-guide#generalresponse-object)[] | | | ### 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`,`QuickReply`、 `Image`、`Video`、`Location`,`Form`,`TransferChat`,`LeaveChat` | | `content` | object | | response's content. when type is `Text`, it represents [OutputText](/docs/guides-bot-integration-third-party-bot-integration-guide#outputtext-object); when type is `QuickReply`,it represents [OutputQuickReply](/docs/guides-bot-integration-third-party-bot-integration-guide#outputquickreply-object);when type is `Image`,it represents [OutputImage](/docs/guides-bot-integration-third-party-bot-integration-guide#outputimage-object);when type is `Video`,it represents [OutputVideo](/docs/guides-bot-integration-third-party-bot-integration-guide#outputvideo-object); when type is `Location`, it represents [OutputLocation](/docs/guides-bot-integration-third-party-bot-integration-guide#outputlocation-object);when type is `Form`, it represents [OutputForm](/docs/guides-bot-integration-third-party-bot-integration-guide#form-object);when type is `TransferChat`, it represents [OutputTransferChat](/docs/guides-bot-integration-third-party-bot-integration-guide#transferchat-object); | | `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](/docs/guides-bot-integration-third-party-bot-integration-guide#textLink-object)[] | | | ### 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](/docs/guides-bot-integration-third-party-bot-integration-guide#option-object)[] | | | | `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 | | --- | --- | --- | --- | | `message` | string | | Message before starting to transfer | | `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](https://user-images.githubusercontent.com/8872646/152307132-9dd5918d-3a18-4fb6-b5b4-84d0f689d561.png) departmentid can obtain from there ![image](https://user-images.githubusercontent.com/8872646/153702520-2b9ebd22-1eb8-4143-8e84-4b0cd1e86ae4.png) ### 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](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotactionsendformfield-object)[] | | an array of [ChatbotActionSendFormField](/docs/guides-bot-integration-third-party-bot-integration-guide#chatbotactionsendformfield-object) | | `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`,`ContactAnAgent`、 `Text` | ### SessionVisitorInfo Object | Name | Type | Default | Description | | --- | --- | --- | --- | | `visitorGuid` | Guid | | | | `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 | | | | `customFields` | [FieldValue](/docs/guides-bot-integration-third-party-bot-integration-guide#fieldvalue-object)[] | | an array of [FieldValue](/docs/guides-bot-integration-third-party-bot-integration-guide#fieldvalue-object) | | `customVariables` | [FieldValue](/docs/guides-bot-integration-third-party-bot-integration-guide#fieldvalue-object)[] | | an array of [FieldValue](/docs/guides-bot-integration-third-party-bot-integration-guide#fieldvalue-object) |