General Integration for Chatbot
Integrating a General Chatbot into CINNOX puts you in control, allowing you to bring your chatbot from any third-party platform and seamlessly integrate it into the CINNOX ecosystem. This integration is achieved by following specific guidelines related to Method, URL, URL Parameters, and HTTP Headers, giving you the confidence to manage the process effectively.
Key Components of Integration:
- Method: The HTTP method (e.g., GET, POST) is used to communicate with the CINNOX platform.
- URL: The endpoint URL where the chatbot will send requests to interact with CINNOX.
- URL Parameters: Specific parameters are included in the URL to ensure proper routing and handling of requests.
- HTTP Headers: Necessary headers that must be included in the HTTP requests for authentication and other purposes.
Benefits of Integration:
- Enhanced Customer Support: Utilize your chatbot as a virtual assistant to handle customer inquiries efficiently.
- Seamless Transition: Easily transfer complex or sensitive customer interactions from the chatbot to live agents on the CINNOX platform.
- Improved Efficiency: Automate routine tasks and provide instant responses to common queries, freeing up live agents for more critical issues.
- Consistent Experience: Maintain a consistent customer experience across different communication channels by integrating your chatbot with CINNOX.
By integrating your chatbot with CINNOX, you can leverage the strengths of both automated and human support to provide a comprehensive and responsive customer service experience.
General Chatbot Settings
To do the general chatbot settings:
- Navigate to Administration > Channels > Destinations from the navigation menu and click the Chatbot tab.
- Click Add Chatbot at the right-hand top corner of the chatbot list.
- Click the dropdown menu to select General Chatbot as the Chatbot Source.
- Fill in the fields Method, URL, URL Parameters and HTTP Headers.
The table below shows examples of URL, URL Parameters and HTTP Headers.
Field | Example | Description |
---|---|---|
Method | POST | It must be POST. This HTTP method means CINNOX will send data to your server to create or update a resource. |
URL | https://jsonplaceholder.typicode.com/todos/1 | The destination to which the enquiry data you require to be sent is CINNOX. It is necessary to be filled in. |
URL Parameter | "enquiryType":chat | The parameters required in the URL. It is optional to be filled in. |
HTTP Headers | "Content-Type": application/json | The HTTP request passes additional context about the request when the data is sent from CINNOX. It is optional to be filled in. |
Request from CINNOX
After the required fields are filled in, CINNOX will send a request in the following format when the destination chatbot must handle the enquiry.
Request Example from CINNOX
{
"query": "string",
"queryParams":{
payload: []byte, //need to unmarshal
},
"inquiryID":"string"
}
- Once the request payload is received, it must be unmarshalled. The example below shows the details after it is unmarshalled.
{
// tag
tagType: "string",
tagId: "string",
tagName: "string",
// channel
channelType: "string",
channelId: "string",
channelName: "string",
channelSourceName: "string",
channelPhoneNumber: "string",
// visitor
visitorName: "string",
visitorPhone: "string",
// others
omniType: "string",
}
Response to CINNOX
The response from the third-party Chatbot must be delivered to CINNOX so that it can reply to the enquiry accordingly. Two response types are available for the general Chatbot in CINNOX: the Text Message and the Advanced Message.
Note
Please send your response, containing the keys and values, to CINNOX in JSON format.
Text Message
A Text Message is a message you can customise with your text. You can use the keys and values below to customise your text message. Based on your keys and values in the response, CINNOX will reply to the enquiry with your text message accordingly.
Key | Type | Value |
---|---|---|
message.type | Number | The value is 1 if it is a text message type, while the value is 5 if it is an advanced message type. |
message.text | String | There are three possible values. - Value = Text (The exact message CINNOX will display to reply to the enquiry in the enquiry chatroom). For example, if the value is " Please contact our customer service support, " the exact message "Please contact our customer service support." will be displayed in the enquiry chatroom as a reply. - Value = DIRECT_TRANSFER This value will trigger the enquiry's transfer from the Chatbot to a live agent after you enable Transfer Chatbot to Live Agent. For details on transferring an enquiry from the Chatbot to a live agent, please refer to the Transfer Enquiry - Chatbot to Live Agent section on this page. - Value = CLOSE_ENQUIRY This value will trigger the automatic close of the enquiry. |
message.advanced | String | The value must be "AdvancedMessage" if the message type is 5. |
Response Example for Text Message
{
"message": {
"type": number,
"text": "string",
"advanced":"string",
}
}
Advanced Message
An Advanced Message is a message you can customise with different formats, actions and components such as Text, Button and Media File using the keys and values listed below. Based on the keys and values in your response, CINNOX will reply to the enquiry with your customised message accordingly.
Format of Message
The advanced message can have different formats: Bubble, Carousel, Quick Reply, List and Text. Their corresponding keys and values are listed in the table below:
Key (Required) | Type | Available Value (Required) |
---|---|---|
advanced.type | Number | The value is 1 when the message format required is Bubble. |
advanced.type | Number | The value is 2 when the message format required is Carousel. |
advanced.type | Number | The value is 3 when the message format required is Quick Reply. |
advanced.type | Number | The value is 4 when the message format needed is List. |
advanced.type | Number | The value is 9 when the message format required is Text. |
Format Example
The table below shows example messages in different formats.
The message content must be displayed in Text, Media File and Button order.
Message Components
Text
The advanced message can have different Text styles, such as Title, Text and Footer.
Key | Type | Available Value |
---|---|---|
advanced.type (It is a key to customising the title, text, or footer.) | Number | The value can be - 1 if the text displayed is required to be in the Bubble format. - 2 if the text displayed is required to be in the Carousel format. |
advanced.items.type (It is a key to customising title, text, or footer.) | Number | The value is 9. (It is a required value to customise Title, Text or Footer.) |
advanced.items.title | String | The title of the message. If the value is "ABC Product, " the title displayed will be "ABC Product. " |
advanced.items.text | String | The body of the message. If the value is "ABC Product, " the body displayed will be "ABC Product. " |
advanced.items.footer | String | The footer of the message. If the value is "ABC Product", the footer displayed will be "ABC Product". |
Note
The title, text and footer must be 10000 characters at most.
Button
The advanced message can consist of buttons with customised functions and actions. Their corresponding keys and values are listed in the table below:
Key | Type | Available Value |
---|---|---|
advanced.type | Number | The value can be: - 1 if the button is required to be in the Bubble format. - 3 if the button is required to be in the Quick Reply format. |
advanced.items.type | Number | The value is 12, which represents a button in the message. |
advanced.items.text | String | The display name of the button. If the value is Customer Service, the display name will be "Customer Service". The display name must be 20 characters at most. |
advanced.items.action.type | String | The value can be: - 0 when no action is required when the visitor presses the button. - 1 for the key = advanced.items.action.text. - 2 for the key = advanced.items.action.url. |
advanced.items.action.text | String | The value can be: - the exact message displayed on the chatroom if the value of advanced.items.action.type is 1 (Postback). For example, if the value is "Thank you for your information", the exact message displayed on the chatroom will be "Thank you for your information" when the visitor presses the button. - DIRECT_TRANSFER. When the visitor presses the button, the enquiry will be transferred to the assigned Staff or Tag. If the Transfer Chatbot to Live Agent is enabled. - CLOSE_ENQUIRY. This value will trigger the automatic close of the enquiry.For details on transferring an enquiry from the Chatbot to a live agent, please refer to the Transfer Enquiry - Chatbot to Live Agent section on this page. |
advanced.items.action.url | String | - The value is the URL if the value of advanced.items.action.type is 2 (URL). The message will direct the visitor to this URL when the visitor presses the button. |
Media Files
The advanced message can consist of various media files such as an image, a video and an audio. Their corresponding keys and values are listed in the table below:
Key | Type | Available Value |
---|---|---|
advanced.items.type | Number | The value is 10 when the media file in the message is an image. Two ratios of the image are available for the image: 1:1 or 1.5:1. |
advanced.items.type | Number | The value is 11 when the media file in the message is a video. |
advanced.items.type | Number | The value is 13 when the media file in the message is audio. |
advanced.items.fileUrl | String | The value is the corresponding URL of the media file in the message. The format of the URL must be like "https://www.grlc/teaching.png". |
Note
Supported formats of media files:
- Image
- JPEG, JPG, PNG and WebP
- Audio
- M4A,W4A, MP3, WAV, MPEG and AAC
- Video
- MP4 and 3GPP
The media file must be 20MB at most.
Examples of Advanced Message
The example keys and values in the response to CINNOX are shown below.
- Quick Reply
{
"advanced": [
{
"type": 1,
"items": [
{
"type": 9,
"title": "Good Result Learning Center",
"text": "Your Exam Expert",
"footer": "Join us now!"
},
{
"type": 10,
"fileUrl": "https://www.grlc/teaching.png"
}
]
},
{
"type": 3,
"items": [
{
"type": 12,
"text": "Website",
"action": {
"type": 2,
"url": "https://www.grlc.com"
}
},
{
"type": 12,
"text": "Email",
"action": {
"type": 1,
"text": "[email protected]"
}
},
{
"type": 12,
"text": "Address",
"action": {
"type": 1,
"text": "Flat 3, 2/F, ABC Building, Castle Peak Road, Tsuen Wan, N.T."
}
}
]
}
]
}
The below image is an example of advanced messages that will reply to the enquiry based on the example keys and values.
- Button List
var advanced = [
{
"type": 1, // TYPE_BUBBLE
"items": [
{
"type": 10, // TYPE_IMAGE
"fileUrl": "https://www.grlc/teaching.png",
},
{
"type": 12, // TYPE_BUTTON
"text": "Button1",
"action": {
"type": 1, // Action.Type TYPE_POSTBACK
"text": "123",
},
},
{
"type": 12, // TYPE_BUTTON
"text": "Button2",
"action": {
"type": 2, // Action.Type TYPE_OPEN_URL
"url": "https://www.grlc.com",
},
},
],
},
];
The below image is an example of advanced messages that will reply to the enquiry based on the example keys and values.
var advanced = [
{
"type": 1, // TYPE_BUBBLE
"items": [
{
"type": 9, // TYPE_TEXT
"title": "Title",
"text": "Body",
"footer": "Footer",
},
{
"type": 10, // TYPE_IMAGE
"fileUrl": "https://www.grlc/teaching.png",
},
{
"type": 12, // TYPE_BUTTON
"text": "Button1",
"action": {
"type": 1, // Action.Type TYPE_POSTBACK
"text": "123",
},
},
{
"type": 12, // TYPE_BUTTON
"text": "Button2",
"action": {
"type": 2, // Action.Type TYPE_OPEN_URL
"url": "https://www.grlc.com",
},
},
],
},
];
The below image is an example of advanced messages that will reply to the enquiry based on the example keys and values.
- List Message
var advanced = [
{
"type": 4, // TYPE_LIST
"items": [
{
"type": 9, // TYPE_TEXT
"title": "I am title",
"text": "I am subtitle"
},
{
"type": 12, // TYPE_BUTTON
"title": "I am item title 1",
"text": "I am item description 1",
"action": {
"type": 1, // Action.Type TYPE_POSTBACK
"text": "I am info key 1"
},
"items":[
{
"type": 10, // TYPE_IMAGE
"fileUrl":"I am imageUri 1"
}
]
},
{
"type": 12, // TYPE_BUTTON
"title": "I am item title 2",
"text": "I am item description 2",
"action": {
"type": 1, // Action.Type TYPE_POSTBACK
"text": "I am info key2"
},
"items":[
{
"type": 10, // TYPE_IMAGE
"fileUrl":"I am imageUri 2"
}
]
}
]
}
];
The below image is an example of advanced messages that will reply to the enquiry based on the example keys and values.
Updated about 2 months ago