General Chatbot

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.

FieldExampleDescription
MethodPOSTIt must be POST. This HTTP method means CINNOX will send data to your server to create or update a resource.
URLhttps://jsonplaceholder.typicode.com/todos/1The destination to which the enquiry data you require to be sent is CINNOX. It is necessary to be filled in.
URL Parameter"enquiryType":chatThe parameters required in the URL. It is optional to be filled in.
HTTP Headers"Content-Type": application/jsonThe 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, the request in the following format will be sent from CINNOX 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 unmarshelled.
{
    // 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.

KeyTypeValue
message.typeNumberThe value is 1 if it is a text message type, while the value is 5 if it is an advanced message type.
message.textStringThere 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 = 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.advancedStringThe 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 your 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)TypeAvailable Value (Required)
advanced.typeNumberThe value is 1 when the message format required is Bubble.
advanced.typeNumberThe value is 2 when the message format required is Carousel.
advanced.typeNumberThe value is 3 when the message format required is Quick Reply.
advanced.typeNumberThe value is 4 when the message format needed is List.
advanced.typeNumberThe 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.

KeyTypeAvailable Value
advanced.type
(It is a key to customise Title, Text or Footer.)
NumberThe 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 customise Title, Text or Footer.)
NumberThe value is 9. (It is a required value to customise Title, Text or Footer.)
advanced.items.titleStringThe title of the message. If the value is "ABC Product", the title displayed will be "ABC Product".
advanced.items.textStringThe body of the message. If the value is "ABC Product", the body displayed will be "ABC Product".
advanced.items.footerStringThe 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:

KeyTypeAvailable Value
advanced.typeNumberThe 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.typeNumberThe value is 12, which represents a button in the message.
advanced.items.textStringThe 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.typeStringThe 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.textStringThe 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.urlString- 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:

KeyTypeAvailable Value
advanced.items.typeNumberThe 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.typeNumberThe value is 11 when the media file in the message is a video.
advanced.items.typeNumberThe value is 13 when the media file in the message is audio.
advanced.items.fileUrlStringThe 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.

{
    "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.