이 페이지는 현재 영어로만 제공되며 한국어 버전은 곧 제공될 예정입니다. 기다려 주셔서 감사드립니다.

단일 채팅 로봇 메시지 콜백

Feature Description

The App backend can perform real-time operations on one-to-one messages by using this callback, including:
Perform real-time logging on one-to-one messages (for example, log recording or message synchronization to other systems).
Perform data statistics on one-to-one messages (for example, statistics on the number of participants or messages).

Must-Knows

To enable the callback, you need to configure the callback URL and turn on the switch corresponding to this callback. For the configuration method, see Webhook Configuration.
The direction of the callback is that the Chat backend sends HTTPS POST requests to the App backend.
After receiving a callback request, the App backend needs to verify whether the value of the SDKAppID parameter in the request URL is its own SDKAppID.
If both the callbacks before sending a one-to-one message and after sending a one-to-one message are enabled at the same time and the callback before sending a one-to-one message returns the error code indicating speaking is prohibited, the callback after sending a one-to-one message will not be triggered.
If both the callbacks before sending a one-to-one message and after sending a one-to-one message are enabled at the same time and the message body is changed for the callback before sending a one-to-one message, the changed message will be used to trigger the callback after sending a one-to-one message.
For other security-related matters, see Security Considerations in Webhook Overview.

Callback Triggering Scenarios

An App user sends a one-to-one message through the client, and the recipient is a chatbot.
An App administrator sends a one-to-one message through a REST API (sendmsg), and the recipient is a chatbot.

Callback Triggering Timing

The callback is triggered after the Chat backend receives a one-to-one message sent by a user and sends the message to the target user. The target user is identified as a chatbot.

API Description

Sample Request URL

In the following example, the callback URL configured for the App is https://www.example.com.
Example:
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

Request Parameters

Parameter
Description
https
The request protocol is HTTPS, and the request method is POST.
www.example.com
Callback URL.
SdkAppid
SDKAppID assigned to an application when the application is created in the Chat console.
CallbackCommand
The value is fixed as Bot.OnC2CMessage.
contenttype
The value is fixed as json.
ClientIP
Client IP address. For example, 127.0.0.1.
OptPlatform
Client platform. For the valid values, see the description of the OptPlatform parameter in Webhook Protocol on Webhook Overview.

Sample Request Packet

{
"CallbackCommand": "Bot.OnC2CMessage", // Callback command.
"From_Account": "jared", // Sender.
"To_Account": "Jonh", // Recipient.
"MsgSeq": 48374, // Message serial number.
"MsgRandom": 2837546, // Message random number.
"MsgTime": 1557481126, // Message sending timestamp, in seconds.
"MsgKey": "48374_2837546_1557481126", // Unique message identifier, which can be used for recalling a one-to-one message by calling a REST API.
"OnlineOnlyFlag":1,//Flag indicating whether to send the message only to online users. 1: send only to online users; 0: send to all users.
"SendMsgResult": 0, // Message sending result.
"ErrorInfo": "send msg succeed", // Error message returned when message sending fails. If the message is sent successfully, "send msg succeed" is returned.
"MsgBody": [ // Message body.
{
"MsgType": "TIMTextElem", // Text.
"MsgContent": {
"Text": "red packet"
}
}
],
"CloudCustomData": "your cloud custom data",
"EventTime": 1670574414123 // Event trigger timestamp, in milliseconds.
}

Request Packet Fields

Field
Type
Description
CallbackCommand
String
Callback command.
From_Account
String
User ID of the message sender.
To_Account
String
User ID of the message recipient.
MsgSeq
Integer
Message serial number (a 32-bit unsigned integer), which is used to identify the message.
MsgRandom
Integer
Message random number (a 32-bit unsigned integer), which is used to identify the message.
MsgTime
Integer
Message sending timestamp, in seconds.
MsgTime is preferentially used for sorting one-to-one messages. For messages sent in the same second, MsgSeq is used for sorting. A message is sent more recently if its MsgSeq value is larger.
MsgKey
String
Unique identifier of the message, which can be used for withdrawing a one-to-one message by calling a REST API.
OnlineOnlyFlag
Integer
Flag indicating whether to send the message only to online users. 1: send only to online users; 0: send to all users.
SendMsgResult
Integer
Sending result of the message. 0: sending successful; other values: sending failed. See Error Codes for details.
ErrorInfo
String
Error message returned when message sending fails. If the message is sent successfully, "send msg succeed" is returned.
MsgBody
Array
Message body. See Message Formats for details.
CloudCustomData
String
Custom message data. (It is saved on the cloud and will be sent to the recipient. It can still be obtained after Chat is uninstalled and then reinstalled.)
EventTime
Integer
Event trigger timestamp, in milliseconds.

Sample Response Packet

The response packet is returned after the App backend synchronizes the data.
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0 // 0: callback successful; 1: callback error.
}

Response Packet Fields

Field
Type
Required
Description
ActionStatus
String
Required
Request processing result:
OK: processing successful.
FAIL: processing failed.
ErrorCode
Integer
Required
Error Code:
0: callback successful.
1: callback error.
ErrorInfo
String
Required
Error message.

References