단일 채팅 로봇 메시지 콜백
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 | |
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
REST API: Sending One-to-One Messages to One User
