Enable and configure AI chatbot
Update time: 2024/03/14 18:45:33
This page describes how to enable and configure third-party AI chatbots in the CommsEase console. Once the AI chatbot settings have been applied, you will be able to engage with the chatbot in both private and group chat sessions.
Prerequisites
You have successfully registered an account for a third-party chatbot service and obtained the API key.
-
Select the application you want to integrate with the Azure OpenAI Service in the Applications section on the homepage of the CommsEase console. In the left-side navigation pane, click Services > Instant Messaging.
-
Go to Account Management, and click Settings in Chatbot.
-
Click Add and configure all the fields for the chatbot service.
-
Specify the chatbot profile
Field Required Description Chatbot accid Yes The chatbot account(accid)
A registered IM account or an unregistered account you can input here and the console will register the account automatically.Chatbot name No The name of the chatbot. Avatar No upload a chatbot avatar in JEP, PNG, or JPEG format. The size of the avatar is 5MB at most. Service No The chatbot service. By default, Azure OpenAI Service is available. You can also use a custom chatbot service. -
Configure the AI chatbot service
Azure OpenAI ServiceIf you choose Azure OpenAI Service, you must specify the required fields for the service. For more information, see the documentation.
Custom AI Chatbot ServiceFor Custom AI Chatbot Service, add the URL of the webhook. The request and format of the webhook must meet the specific API specification. Otherwise, the CommsEase server will not process the requests.
-
Configure the messaging logic.
Field Required Description The number of rewindable messages Yes The limit on the number of rewindable messages sent to Azure OpenAI Service The time limit for rewindable messages Yes The limit on the time for message rewinding. Whether replies are returned without moderation Yes The replies from the chatbot service are not synced with the app server or moderated by the CommsEase moderator. The default value is Yes.
-
-
Click Save to complete the configuration. You can start chatting with the chatbot.
Multiple chatbots are allowed even with the same webhook URL.
Webhook API specification
The request and format of the custom webhook must meet the specific API specification. Otherwise, the CommsEase server will not process the requests.
Request format
Request header
Header parameters:
Parameter | Type | Description |
---|---|---|
AppKey |
String | The AppKey of your application. For more information, see Get AppKey |
CurTime |
Long | the number of milliseconds from January 1, 1970 at 0:00:0 to the present time. |
MD5 |
String | The MD5 value calculated based on the request body in the request. |
CheckSum |
String | CheckSum verification value |
Content-Type |
String | Request body type, application/json |
-
MD5 value calculation example:
java
String requestBody = "{}"; String MD5 = CheckSumBuilder.getMD5(requestBody); // See, API overview -> API checksum
-
CheckSum calculation:
java
String AppSecret = "90ud57s6****"; String MD5 = "9894907e4ad9de467809127750******"; String CurTime = "1440570500855"; ////The current UTC timestamp. The number of seconds from January 1, 1970 at 00:00:00 to the present in String format String CheckSum = CheckSumBuilder.getCheckSum(AppSecret, MD5, CurTime); //See API reference overview -> API checksum verification section.
Request body
The body data must be in JSON format.
Fields:
Parameter | Type | Required | Description |
---|---|---|---|
msg | JSON | Yes | The message sent to the chatbot. |
fromAccount | String | Yes | Sender accocunt, accid |
to | String | Yes | Chatbot account (accid) for private chats, group ID (teamId) for group chats. |
robotAccid | String | Yes | Chatbot account(accid) |
robotFunction | String | Yes | Chatbot service |
robotTopic | String | No | the topic of the message |
robotCustomContent | String | No | Custom content |
msgType | String | Yes | Message type, TEXT: text message; PICTURE: image message; AUDIO: audio message; VIDEO: video message; LOCATION: geolocation; NOTIFICATION: notification; FILE: file message; TIPS: alert; CUSTOM : custom message |
body | String | No | Message body, optional for some types of message, but attach is required |
attach | String | No | Message attachment, optional for some types of messages, but body is required. |
ext | String | No | Extension field |
msgTimestamp | Long | No | timestamp when a message was sent |
msgidClient | String | No | Client-side message ID |
msgidServer | Long | No | Server-side message ID |
lastMsgs | JSONArray | No | Messages to be backtracked, each element contains a message. |
Example:
java{
"msg": {
"fromAccount": "xx",
"to": "acc2",
"robotAccid": "acc2",
"robotFunction": "acc2",
"robotTopic": "aaa",
"robotCustomContent": "xx",
"msgType": "TEXT",
"body": "XX",
"attach": "xx",
"ext": "xx",
"msgTimestamp": 123,
"msgidClient": "xxx",
"msgidServer": 222
},
"lastMsgs": [
{},
{}
]
}
Response format
Set the Content-Type of the response header to application/json; charset=utf-8
.
The response body is in JSON format, for example:
java{
"code":200,
"data":{
"type":0,
"body":"xxx",
"antispam":false
}
}
The reply message sent by the chatbot is contained in the data
. The following table describes specific parameters:
Click to see the specific parameter
Parameter | Type | Description |
---|---|---|
type | Integer |
|
body | String | Message body, the maximum length of the body field can contain 5,000 characters |
msgDesc | String | Message description for other than text messages and alerts. A maximum of 500 characters are allowed. The description can be used for keyword search for message history stored in the cloud |
antispam | Boolean |
Whether to moderate custom messages if the moderation service is enabled. The default value is false. |
antispamCustom | String |
The parameter is valid only if the antispam parameter is set to true. Custom content for moderation in JSON format, the length limit is the same as the body field, and cannot exceed 5,000 characters. The format of antispamCustom: {"type":1,"data":"custom content"} Fields: 1. type: 1: text; 2: image; 3: video 2. data: Text or image URL |
option | String |
Special options for sending a message in JSON format, such as roaming, cloud history storage, sender multi-device sync, push notification, and data sync. If the option field is unspecified, the default value is applied.
,option example: {"push":false,"roam":true,"history":false,"sendersync":true,"route":false,"badge":false,"needPushNick":true} Fields:
|
pushcontent | String |
The body of a push notification, Up to 500 characters. The payload of a push notification can be configured only after the push field is set to true in the option. If the pushcontent is unspecified, the default content will be used. The rules for the content copy:
|
payload | String | The payload of a push notification must be in JSON format and cannot exceed 2,048 characters. For more information about push notifications, see Configure parameters for the push notification service. |
ext | String | Extension field must be in JSON format and contain up to 1,024 characters |
forcepushall | Boolean | When sending a group message, whether the list of users to receive push notifications (@ mention operation) contains all valid members in the group except the sender. The default value is false. |
forcepushlist | String |
A list of users to receive push notifications (@ mention operation) when sending group messages in JSONArray, such as ["accid1","accid2"]. If forcepushall is set to true, the forcepushlist contains all valid group members except the sender. |
forcepushcontent | String | When sending a group message, the content that is force pushed for the users in the list of members for force-push. A maximum of 500 characters are allowed. |
useYidun | Integer |
Whether a message (including custom messages) uses Content Moderator provided by GuardEase. Only 0 is valid. Other values are equal to an empty value. 0: (if Safe Pass has been activated) Do not use Content Moderator If unspecified, by default, use Content Moderator provided by GuardEase to check the content if the application has enabled the Content Moderator service. |
bid | String | ID of the Content Moderator service. You can specify the current message to be moderated by Content Moderation of a certain configuration. If unspecified, the original configuration will be used. |
yidunAntiCheating | String |
The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase exclusive fields. |
yidunAntiSpamExt | String |
The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase extension field) |
markRead | Integer | Whether read receipt is required for group messages, 0: No, 1: Yes |
async | Boolean | Whether async call is enabled. The default value is false. |
checkFriend | Boolean |
Whether the message is sent to only friends. The default value is false |
subType | Integer | Custom message type, greater than 0 |
msgSenderNoSense | Integer |
Whether the message is recorded for the sender. 0: Yes, 1: No. The default value is 0. If the value is set to 1, the message will not be synced across devices or stored in message history for the sender. |
msgReceiverNoSense | Integer |
Whether the message is recorded for the recipient. 0: Yes, 1: No The default value is 0. If the value is set to 1, the message will not be synced across devices or stored in message history for the recipient. |
env | String | The environment name for data sync, consistent with the environment name specified in the CommsEase console for data sync as shown in the figure below. A maximum of 32 characters are allowed. |
- Not every field in the message body will be returned. Note the null evaluation of each field.
- You can see the parameters in the message sending interface (/msg/sendMsg.action) for the parameters in reply messages from a chatbot.