Activate and configure AI chatbot service

Update time: 2023/10/24 09:37:25

This page provides instructions on enabling and configuring third-party AI chatbots within the console.

You can engage with the chatbot in private or group chats once the chatbot settings have been activated.

Prerequisites

You have registered the account for a third party chatbot service and get the API key.

Workflow

  1. Select the application you want to integrate with the Azure OpenAI Service in the Applications section on the homepage of the console. In the left-side navigation pane, click Services > Instant Messaging.

  2. Go to Account Management, and click Settings in Chatbot.

    Chatbot.png

  3. Click Add Chatbot and configure all the fields for the chatbot service.

    • Specify the chatbot information.

      Chatbot_info.png

      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.

      OpenAI_bot.png

      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] (#webhook-API specification). Otherwise, the CommsEase server will not process the requests.

      Custom_bot.png

    • Configure the messaging logic.

      Message_logic.png

      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.
  4. 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 syntax

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:

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

    
        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.
lastMsgs JSONArray No Messages to be backtracked, each element contains a message.

Example:

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

Set the Content-Type of the response header to application/json; charset=utf-8.

The response body is in JSON format, for example:

{
  "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 ​ ​ ​
ParameterTypeDescription
typeInteger
  • 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.
bodyString Message body, the maximum length of the body field can contain 5,000 characters
msgDescStringMessage 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 (Sync webhooks must be endabled);
  • 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 cand annot exceed 2048 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 forcepushlist, 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 fieldThe 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 API (/msg/sendMsg.action for the parameters in reply messages from a chatbot.
    Was this page helpful?
    Yes
    No
    • Prerequisites
    • Workflow
    • Webhook API specification
    • Request syntax
    • Request header
    • Request body
    • Response syntax