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 Service
If you choose Azure OpenAI Service, you must specify the required fields for the service. For more information, see the documentation.

Custom AI Chatbot Service
For 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:

javaString requestBody = "{}";
String MD5 = CheckSumBuilder.getMD5(requestBody); // See, API overview -> API checksum

CheckSum calculation:

javaString 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	0: Text message 1: image message 2: audio message 3: video message 4: location message< /li> 6: file message 10: alert message 100: custom message, If the for unsubscribedcontent moderation service is not activated, the custom message will not be reviewed.
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. The parameter is valid only for custom messages (message type: 100).
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: roam: Whether the message is roamed. The default value is true (roaming must be activated) history: Whether the message is stored in the cloud. The default value is true. sendersync: Whether the message is synced on multiple devices. The default value is true push: Whether the message is sent using APNs or an Android push service. The default value is true route: Whether the message is synced to the specified application server. The default value is true (Data sync must be enabled); badge: Whether the message is counted as unread. The default value is true; needPushNick: Whether the payload of a push notification adds a nickname. If unspecified, the default value true is applied. persistent: Whether the message is stored for offline devices. If unspecified, the default value true is applied. Offline messages are the messages sent from others when a user is offline. If messages are stored for offline devices, offline messages are temporarily stored on the IM server during the offline period and automatically delivered to the client SDK when uses log in. For P2P chats, the most recent 5,000 offline messages in the last 30 days are stored, Each session can contain up to 100 recent offline messages. For group chats, the offline messages in the most recent 30 days are stored. Each group chat session can contain up to 100 recent offline messages. sessionUpdate: Whether to update this message to the last message (lastmsg) of this conversation. The default value is true
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: pushcontent is not empty and needPushNick=true, the final content is: the nickname of the pusher + pushcontent pushcontent is not empty and needPushNick=false, the final content copy: pushcontent pushcontent is empty and needPushNick=true, the final content: pusher nickname + default content pushcontent is empty and needPushNick=false, the final content: default content According to the message type, the default content is divided into the following types: Text message: A message was sent Location message: A geolocation was sent Audio message: an audio message was sent Video message: A video message was sent File message: A file was sent Image message: An image was sent Audio call invite: you are invited for an audio call Video call invite: you are invited for a video call
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. Up to 100 users. If the vale exceeds the upper limit, an error will be thrown(status code: 811).
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. The email, phone number, token, and extension parameters are included in yidunAntiCheating. Additional data are sent to yidunAntiSpamExt. The value passed in by yidunAntiSpamExt overrides the extension by default.
yidunAntiSpamExt	String	The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase extension field）The email, phone number, token, and extension parameters are included in yidunAntiCheating. Additional data are sent to yidunAntiSpamExt.
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 If only friends can receive messages, you must complete the settings in the CommsEase console.
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.You can specify wether the message can be stored in the message history. For more information, see Query message history for private chats and Query message history for group chats.
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. You can specify wether the message can be stored in the message history. For more information, see Query message history for private chats and Query message history for group chats.
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.

Was this page helpful?

Yes

Prerequisites
Webhook API specification
Request format
Request header
Request body
Response format