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.

General Chatbot

General Chatbot Settings

Request from CINNOX

Response to CINNOX

📘
Note

Text Message

Advanced Message

Format of Message

📘

Message Components

📘
Note

📘
Note

Examples of Advanced Message

General Chatbot Settings

Request from CINNOX

Response to CINNOX

📘Note

Text Message

Advanced Message

Format of Message

📘

Message Components

📘Note

📘Note

Examples of Advanced Message

📘
Note

📘
Note

📘
Note