From 4e202473ef7276407b8b4d052e50ba2f4015556a Mon Sep 17 00:00:00 2001 From: mo3et Date: Thu, 30 Oct 2025 16:36:26 +0800 Subject: [PATCH 1/3] feat: add webhook docs. --- .../webhooks/msg/groupMsgReadAfter.mdx | 79 +++++++++++++ .../webhooks/msg/sendGroupMsgAfter.mdx | 111 ++++++++++++++++++ .../webhooks/msg/sendGroupMsgBefore.mdx | 103 ++++++++++++++++ .../webhooks/push/groupOnlinePushBefore.mdx | 104 ++++++++++++++++ .../webhooks/msg/groupMsgReadAfter.mdx | 77 ++++++++++++ .../webhooks/msg/sendGroupMsgAfter.mdx | 106 +++++++++++++++++ .../webhooks/msg/sendGroupMsgBefore.mdx | 106 +++++++++++++++++ .../webhooks/push/groupOnlinePushBefore.mdx | 106 +++++++++++++++++ 8 files changed, 792 insertions(+) create mode 100644 docs/restapi/webhooks/msg/groupMsgReadAfter.mdx create mode 100644 docs/restapi/webhooks/msg/sendGroupMsgAfter.mdx create mode 100644 docs/restapi/webhooks/msg/sendGroupMsgBefore.mdx create mode 100644 docs/restapi/webhooks/push/groupOnlinePushBefore.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/groupMsgReadAfter.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgAfter.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgBefore.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/push/groupOnlinePushBefore.mdx diff --git a/docs/restapi/webhooks/msg/groupMsgReadAfter.mdx b/docs/restapi/webhooks/msg/groupMsgReadAfter.mdx new file mode 100644 index 0000000000..93cde9e21c --- /dev/null +++ b/docs/restapi/webhooks/msg/groupMsgReadAfter.mdx @@ -0,0 +1,79 @@ +--- +title: 群聊消息已读上报后回调 +hide_title: true +--- + +# 群聊消息已读上报后回调 + +## 功能说明 +App 业务服务端可以通过该回调实时查看用户的群聊消息的已读动作。 + +## 注意事项 +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- APP 业务服务端需在超时时间内响应此请求。 + +## 可能触发该回调的场景 +- App 用户通过客户端做群聊消息的已读上报。 +- App 管理员通过 REST API 接口 设置群聊消息已读。 + + +## 回调发生时机 + +- 群聊消息已读上报成功之后。 + +## 接口说明 + +### 请求 URL 示例 +此处`CallbackCommand`为：`callbackAfterSingleMsgReadCommand` +```plaintext +{WEBHOOK_ADDRESS}/callbackAfterSingleMsgReadCommand?contenttype=json +``` + +### 请求包示例 + +```json +{ + "callbackCommand": "callbackAfterSingleMsgReadCommand", + "conversationID": "si_u1_u2:0" + "userID": "user123", + "seqs": [20, 35], + "contentType": 101 +} +``` + +### 请求包字段说明 + +| 对象 | 类型 | 描述 | +|-----------------|--------|----------------------------| +| callbackCommand | string | 回调命令，这里是群聊消息已读回调 | +| conversationID | string | 会话ID | +| userID | string | 接收消息的用户ID | +| contentType | int32 | 消息类型 | +| seqs | []int64 | 已读消息序列 | + + +## 应答包示例 + +### 成功应答 +成功接收并处理用户已读群聊消息的请求。 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + +## 应答包字段说明 + +| 字段 | 值 | 说明 | +|-------------|------------------------------|------------------------------------------| +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 20001 | 表示自定义错误码，范围在20001-29999之间。在 actionCode 不等于0时设置；在 nextCode 不等于1时设置。| +| errMsg | "An error message" | 自定义错误码对应的简单错误信息。| +| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。| +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。| diff --git a/docs/restapi/webhooks/msg/sendGroupMsgAfter.mdx b/docs/restapi/webhooks/msg/sendGroupMsgAfter.mdx new file mode 100644 index 0000000000..e4b2f9d76c --- /dev/null +++ b/docs/restapi/webhooks/msg/sendGroupMsgAfter.mdx @@ -0,0 +1,111 @@ +--- +title: 发送群聊消息后的回调 +hide_title: true +--- + +# 发送群聊消息后的回调 + +## 功能说明 +App 业务服务端可以通过该回调实时对用户的群聊消息进行操作，如： +- 对发群聊消息进行实时记录（记录日志或同步到其他系统）。 +- 对群聊消息进行数据统计（统计人数、消息数等）。 + +## 注意事项 +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- APP 业务服务端需在超时时间内响应此请求。 + +## 可能触发该回调的场景 +- App 用户通过客户端发送群聊消息。 +- App 管理员通过 REST API 发送群聊消息 + +## 回调发生时机 +- OpenIMServer 收到用户发送的群聊消息，并将该消息下发给目标用户之后。 + +## 接口说明 + +### 请求 URL 示例 +此处`CallbackCommand`为：`callbackAfterSendGroupMsgCommand` +```plaintext +{WEBHOOK_ADDRESS}/callbackAfterSendGroupMsgCommand?contenttype=json +``` + +### 请求包示例 +```json +{ + "sendID": "user123", + "callbackCommand": "callbackAfterSendGroupMsgCommand", + "serverMsgID": "serverMsg123", + "clientMsgID": "clientMsg123", + "operationID": "1646445464564", + "senderPlatformID": 1, + "senderNickname": "John Doe", + "sessionType": 1, + "msgFrom": 1, + "contentType": 1, + "status": 1, + "sendTime": 1673048592000, + "createTime": 1673048592000, + "content": "Hello, how are you?", + "seq": 1, + "atUserList": ["user456", "user789"], + "faceURL": "http://example.com/path/to/face/image.png", + "ex": "Extra data", + "recvID": "user456" +} +``` + + + + +### 请求包字段说明 + +| 对象 | 类型 | 描述 | +|--------------------|--------|------------------------------------------------------ | +| sendID | string | 发送者的用户ID | +| callbackCommand | string | 回调命令，这里是发送群聊消息后的回调 | +| serverMsgID | string | 服务器生成的消息ID | +| clientMsgID | string | 客户端生成的消息ID | +| operationID | string | operationID用于全局链路追踪 | +| senderPlatformID | int32 | 发送者的平台ID | +| senderNickname | string | 发送者的昵称 | +| sessionType | int32 | 会话类型,1：单聊，2：群聊，4：系统通知 | +| msgFrom | int32 | 消息来源，100来源于用户发送，200来源于管理员发送或者系统广播通知等 | +| contentType | int32 | 消息内容类型，101表示文本消息，102表示图片消息，103表示语音消息，... | +| status | int32 | 消息状态，1表示发送成功，2表示发送失败 | +| sendTime | int64 | 消息发送的时间戳（毫秒） | +| createTime | int64 | 消息创建的时间戳（毫秒） | +| content | string | 消息内容 | +| seq | uint32 | 消息序号 | +| atUserList | string | 群聊成员ID列表，单聊忽略 | +| faceURL | string | 发送者的头像URL | +| ex | string | 额外的数据字段 | +| recvID | string | 接收者的用户ID | + + +## 应答包示例 + +### 成功响应 +App 业务服务端同步数据后，发送回调应答包 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + + + +## 应答包字段说明 +| 字段 | 值 | 说明 | +|-------------|------------------------------|------------------------------------------| +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 0 | 表示自定义错误码，此处填0代表忽略回调结果。| +| errMsg | "An error message" | 自定义错误码对应的简单错误信息。| +| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。| +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode等于`0`时设置。| + diff --git a/docs/restapi/webhooks/msg/sendGroupMsgBefore.mdx b/docs/restapi/webhooks/msg/sendGroupMsgBefore.mdx new file mode 100644 index 0000000000..accde722d3 --- /dev/null +++ b/docs/restapi/webhooks/msg/sendGroupMsgBefore.mdx @@ -0,0 +1,103 @@ +--- +title: 发送群聊消息前的回调 +hide_title: true +--- + +# 在发送群聊消息前的回调 + +## 功能说明 +App 业务服务端可以通过该回调实时对用户的群聊信息进行操作，如：对发群聊信息进行实时记录，拦截用户的违规发言请求。 + +## 注意事项 +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- APP 业务服务端需在超时时间内响应此请求。 + +## 可能触发该回调的场景 +- App 用户通过客户端发送群聊消息。 +- App 管理员通过 REST API 发送群聊信息。 + +## 回调发生时机 +- OpenIMServer 收到用户发送的群聊信息之后、将该信息下发给目标用户之前。 + +## 接口说明 + +### 请求 URL 示例 +此处`CallbackCommand`为：`callbackBeforeSendGroupMsgCommand` +```plaintext +{WEBHOOK_ADDRESS}/callbackBeforeSendGroupMsgCommand?contenttype=json +``` + +### 请求包示例 +```json +{ + "sendID": "user123", + "callbackCommand": "callbackBeforeSendGroupMsgCommand", + "serverMsgID": "msg001", + "clientMsgID": "clientmsg001", + "operationID": "1646445464564", + "senderPlatformID": 1, + "senderNickname": "User123", + "sessionType": 1, + "msgFrom": 1, + "contentType": 1, + "status": 1, + "sendTime": 1673048592000, + "createTime": 1673048592000, + "content": "Hello, this is a test message", + "seq": 1001, + "atUserList": ["user456", "user789"], + "faceURL": "http://example.com/path/to/user/image.png", + "ex": "Extra data", + "recvID": "user456" +} +``` + +### 请求包字段说明 + +| 对象 | 类型 | 描述 | +|-----------------|---------|------------------------------------------------------------| +| sendID | string | 发送者的用户ID | +| callbackCommand | string | 回调命令，这里是发送群聊消息前的回调 | +| serverMsgID | string | 服务器分配的消息ID | +| clientMsgID | string | 客户端分配的消息ID | +| operationID | string | operationID用于全局链路追踪 | +| senderPlatformID| int32 | 发送者的平台ID | +| senderNickname | string | 发送者的昵称 | +| sessionType | int32 | 会话类型 | +| msgFrom | int32 | 消息来源 | +| contentType | int32 | 消息内容的类型 | +| status | int32 | 消息的状态 | +| sendTime | int64 | 消息发送的时间戳（毫秒） | +| createTime | int64 | 消息创建的时间戳（毫秒） | +| content | string | 消息内容 | +| seq | uint32 | 消息序列号 | +| atUserList | array | 群组成员ID列表，单聊忽略 | +| faceURL | string | 发送者头像的URL | +| ex | string | 额外的数据字段 | +| recvID | string | 接收者的用户ID | + +## 应答包示例 + +### 允许发送 +允许用户发送消息。 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + +## 应答包字段说明 + +| 字段 | 值 | 说明 | +|-----------------|----------|--------------------------------------------| +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 5001 | 表示自定义错误码，范围在5000-9999之间。在 actionCode 不等于0时设置；在 nextCode 等于1时设置。| +| errMsg | "消息" | 自定义错误码对应的简单错误信息。 | +| errDlt | "详细信息" | 自定义错误码对应的详细错误信息。 | +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。| diff --git a/docs/restapi/webhooks/push/groupOnlinePushBefore.mdx b/docs/restapi/webhooks/push/groupOnlinePushBefore.mdx new file mode 100644 index 0000000000..9a75ff2f48 --- /dev/null +++ b/docs/restapi/webhooks/push/groupOnlinePushBefore.mdx @@ -0,0 +1,104 @@ +--- +title: 在线状态下群消息推送前的回调 +hide_title: true +--- + +# 在线状态下群消息推送前的回调 + +## 功能说明 + +在消息发送至客户端前，App 业务服务端可以通过该回调接收到发送消息的请求。业务服务端可以根据需要对消息进行拦截、修改或添加额外的推送信息。 + +## 注意事项 + +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- App 业务服务端在收到回调请求后，需在超时时间内做出响应。 + +## 可能触发该回调的场景 + +- 群成员退出群组。 +- 群成员被踢出群组。 +- 群组解散。 + +## 回调发生时机 + +- OpenIMServer 准备向客户端推送消息前。 + +## 接口说明 + +### 请求 URL 示例 + +此处`CallbackCommand`为：`callbackBeforeGroupOnlinePushCommand` +```plaintext +{WEBHOOK_ADDRESS}/callbackBeforeGroupOnlinePushCommand?contenttype=json +``` + +### 请求包示例 + +```json +{ + "callbackCommand": "callbackBeforeGroupOnlinePushCommand", + "platformID": 1, + "platform": "iOS", + "clientMsgID": "msg123", + "sendID": "user789", + "groupID": "group123", + "contentType": 1, + "sessionType": 2, + "atUserIDList": ["user101", "user102"], + "content": "Hello, this is a test message" +} +``` + +### 请求包字段说明 + +| 字段 | 类型 | 描述 | +| --------------- | ------- | ---------------------------------------- | +| callbackCommand | string | 回调命令，这里是群消息推送前的回调 | +| platformID | int | 平台 ID（如 1 代表 iOS，2 代表 Android） | +| platform | string | 平台名称（如 iOS、Android） | +| clientMsgID | string | 客户端消息 ID | +| sendID | string | 发送者 ID | +| groupID | string | 群组 ID（如果消息是发送到群组的） | +| contentType | int | 消息内容类型的 ID | +| sessionType | int | 会话类型的 ID | +| atUserIDList | array | 被@用户的 ID 列表 | +| content | string | 发送的消息内容 | + +## 应答包示例 + +### 允许推送 + +允许消息被推送到客户端。 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": "", + "userIDList": ["user123", "user456"], + "offlinePushInfo": { + "title": "New Message", + "desc": "You have a new message", + "ex": "Extra push info", + "iOSPushSound": "default", + "iOSBadgeCount": true, + "signalInfo": "Signal data" + } +} +``` + +## 应答包字段说明 + +| 字段 | 类型 | 描述 | +| --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- | +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 5001 | 表示自定义错误码，范围在 5000-9999 之间。在 actionCode 不等于 0 时设置；在 nextCode 等于 1 时设置。 | +| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 | +| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 | +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 | +| userIDList | array | 用户 ID 列表，表示允许接收消息的用户。 | +| offlinePushInfo | object | 离线推送信息对象。 | diff --git a/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/groupMsgReadAfter.mdx b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/groupMsgReadAfter.mdx new file mode 100644 index 0000000000..9d0812e8e5 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/groupMsgReadAfter.mdx @@ -0,0 +1,77 @@ +--- +title: Callback After Group Chat Message Read Report +hide_title: true +--- + +# Callback After Group Chat Message Read Report + +## Description +The App backend can use this callback to view the read status of users' Group Chat messages in real-time. + +## Important Notes +- To enable this callback, configure the callback URL and activate the corresponding protocol switch. For configuration details, see the [Callback Introduction](../introduction) document. +- The callback direction is from OpenIMServer to the App backend as an HTTP/HTTPS POST request. +- The App backend must respond to this request within the specified timeout. + +## Scenarios that Trigger This Callback +- An App user reports a Group Chat message as read through the client. +- An administrator sets a Group Chat message as read through the REST API. + +## Timing of Callback +- After a Group Chat message is successfully marked as read. + +## Interface Description + +### Example Request URL +The `CallbackCommand` here is: `callbackAfterSingleMsgReadCommand` + +```plaintext +{WEBHOOK_ADDRESS}/callbackAfterSingleMsgReadCommand?contenttype=json +``` + +### Example Request Package + +```json +{ + "callbackCommand": "callbackAfterSingleMsgReadCommand", + "conversationID": "si_u1_u2:0", + "userID": "user123", + "seqs": [20, 35], + "contentType": 101 +} +``` + +### Request Package Field Descriptions + +| Field | Type | Description | +|-------------------|------------|-----------------------------------------| +| callbackCommand | string | Callback command for the Group Chat message read report | +| conversationID | string | Conversation ID | +| userID | string | User ID of the message receiver | +| contentType | int32 | Message content type | +| seqs | []int64 | Sequence numbers of the read messages | + +## Example Response Package + +### Success Response +The backend successfully receives and processes the Group Chat message read report. + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + +## Response Package Field Descriptions + +| Field | Value | Description | +|---------------|---------------------------|-------------------------------------------------------------| +| actionCode | 0 | Indicates whether the callback was successfully executed. `0` means success. | +| errCode | 20001 | Custom error code, ranges from 20001-29999, set when `actionCode` is not 0, or `nextCode` is not 1 | +| errMsg | "An error message" | Simple error message for the custom error code | +| errDlt | "Detailed error information" | Detailed error message | +| nextCode | 1 | Next step directive, `1` to halt further action if `actionCode` is `0` | diff --git a/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgAfter.mdx b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgAfter.mdx new file mode 100644 index 0000000000..d93dcea963 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgAfter.mdx @@ -0,0 +1,106 @@ +--- +title: Callback After Sending Group Chat Message +hide_title: true +--- + +# Callback After Sending Group Chat Message + +## Description +The App backend can use this callback to perform actions on Group Chat messages, such as: +- Logging Group Chat messages in real-time (for logs or synchronization with other systems). +- Performing data analysis on Group Chat messages (e.g., counting users or messages). + +## Important Notes +- To enable this callback, configure the callback URL and activate the corresponding protocol switch. For configuration details, see the [Callback Introduction](../introduction) document. +- The callback direction is from OpenIMServer to the App backend as an HTTP/HTTPS POST request. +- The App backend must respond to this request within the specified timeout. + +## Scenarios that Trigger This Callback +- A user sends a Group Chat message through the client. +- An administrator sends a Group Chat message via the REST API. + +## Timing of Callback +- After OpenIMServer receives the user’s Group Chat message and distributes it to the target user. + +## Interface Description + +### Example Request URL +The `CallbackCommand` here is: `callbackAfterSendSingleMsgCommand` + +```plaintext +{WEBHOOK_ADDRESS}/callbackAfterSendSingleMsgCommand?contenttype=json +``` + +### Example Request Package +```json +{ + "sendID": "user123", + "callbackCommand": "callbackAfterSendSingleMsgCommand", + "serverMsgID": "serverMsg123", + "clientMsgID": "clientMsg123", + "operationID": "1646445464564", + "senderPlatformID": 1, + "senderNickname": "John Doe", + "sessionType": 1, + "msgFrom": 1, + "contentType": 1, + "status": 1, + "sendTime": 1673048592000, + "createTime": 1673048592000, + "content": "Hello, how are you?", + "seq": 1, + "atUserList": ["user456", "user789"], + "faceURL": "http://example.com/path/to/face/image.png", + "ex": "Extra data", + "recvID": "user456" +} +``` + +### Request Package Field Descriptions + +| Field | Type | Description | +|---------------------|----------|--------------------------------------------------------------------------| +| sendID | string | Sender's user ID | +| callbackCommand | string | Callback command, here used for the callback after sending a Group Chat message | +| serverMsgID | string | Server-generated message ID | +| clientMsgID | string | Client-generated message ID | +| operationID | string | Used for global tracking | +| senderPlatformID | int32 | Sender's platform ID | +| senderNickname | string | Sender's nickname | +| sessionType | int32 | Session type, `1`: single chat, `2`: group chat, `4`: system notification | +| msgFrom | int32 | Message source, `100`: user sent, `200`: admin or system notification | +| contentType | int32 | Content type of the message, `101`: text, `102`: image, `103`: voice, etc. | +| status | int32 | Message status, `1`: sent successfully, `2`: failed | +| sendTime | int64 | Timestamp when the message was sent (milliseconds) | +| createTime | int64 | Timestamp when the message was created (milliseconds) | +| content | string | Content of the message | +| seq | uint32 | Message sequence number | +| atUserList | string | List of group member IDs, ignore for single chat | +| faceURL | string | Sender's avatar URL | +| ex | string | Extra data field | +| recvID | string | Receiver's user ID | + +## Example Response Package + +### Success Response +The App backend sends a callback response after synchronizing data. + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + +### Response Package Field Descriptions + +| Field | Value | Description | +|---------------|------------------------------|-------------------------------------------------------------| +| actionCode | 0 | Indicates whether the callback was successfully executed. `0` means success. | +| errCode | 0 | Custom error code, set to 0 to ignore the callback result | +| errMsg | "An error message" | Simple error message for the custom error code | +| errDlt | "Detailed error information" | Detailed error information | +| nextCode | 1 | Next step directive; `1` to halt further action if `actionCode` = `0` | diff --git a/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgBefore.mdx b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgBefore.mdx new file mode 100644 index 0000000000..72183a8c03 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/msg/sendGroupMsgBefore.mdx @@ -0,0 +1,106 @@ +--- +title: Callback Before Sending Group Chat Message +hide_title: true +--- + +# Callback Before Sending Group Chat Message + +## Description +The App backend can use this callback to take action on Group Chat messages in real-time, such as: +- Logging Group Chat messages. +- Blocking user requests with inappropriate content. + +## Important Notes +- To enable this callback, configure the callback URL and activate the corresponding protocol switch. For configuration details, see the [Callback Introduction](../introduction) document. +- The callback direction is from OpenIMServer to the App backend as an HTTP/HTTPS POST request. +- The App backend must respond to this request within the specified timeout. + +## Scenarios that Trigger This Callback +- A user sends a Group Chat message through the client. +- An administrator sends a Group Chat message via the REST API. + +## Timing of Callback +- After OpenIMServer receives the user’s Group Chat message but before distributing it to the target user. + +## Interface Description + +### Example Request URL +The `CallbackCommand` here is: `callbackBeforeSendSingleMsgCommand` + +```plaintext +{WEBHOOK_ADDRESS}/callbackBeforeSendSingleMsgCommand?contenttype=json +``` + +### Example Request Package +```json +{ + "sendID": "user123", + "callbackCommand": "callbackBeforeSendSingleMsgCommand", + "serverMsgID": "msg001", + "clientMsgID": "clientmsg001", + "operationID": "1646445464564", + "senderPlatformID": 1, + "senderNickname": "User123", + "sessionType": 1, + "msgFrom": 1, + "contentType": 1, + "status": 1, + "sendTime": 1673048592000, + "createTime": 1673048592000, + "content": "Hello, this is a test message", + "seq": 1001, + "atUserList": ["user456", "user789"], + "faceURL": "http://example.com/path/to/user/image.png", + "ex": "Extra data", + "recvID": "user456" +} +``` + +### Request Package Field Descriptions + +| Field | Type | Description | +|---------------------|----------|------------------------------------------------------------| +| sendID | string | Sender's user ID | +| callbackCommand | string | Callback command, used for callback before sending a Group Chat message | +| serverMsgID | string | Server-assigned message ID | +| clientMsgID | string | Client-assigned message ID | +| operationID | string | Used for global tracking | +| senderPlatformID | int32 | Sender's platform ID | +| senderNickname | string | Sender's nickname | +| sessionType | int32 | Type of session | +| msgFrom | int32 | Source of the message | +| contentType | int32 | Type of the content | +| status | int32 | Status of the message | +| sendTime | int64 | Timestamp of message sent (milliseconds) | +| createTime | int64 | Timestamp of message creation (milliseconds) | +| content | string | Message content | +| seq | uint32 | Sequence number of the message | +| atUserList | array | List of group member IDs; ignore for single chat | +| faceURL | string | URL for sender's avatar | +| ex | string | Extra data field | +| recvID | string | Receiver's user ID | + +## Example Response Package + +### Allow Message Sending +Allowing the user to send the message. + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + +### Response Package Field Descriptions + +| Field | Value | Description | +|---------------|------------------------------|-------------------------------------------------------------| +| actionCode | 0 | Indicates whether the callback was successfully executed. `0` means success. | +| errCode | 5001 | Custom error code, ranges from 5000-9999, set when `actionCode` is not 0, or `nextCode` is 1 | +| errMsg | "Message" | Simple error message for the custom error code | +| errDlt | "Detailed information" | Detailed error message | +| nextCode | 1 | Next step directive, `1` to halt further action if `actionCode` is `0` | diff --git a/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/push/groupOnlinePushBefore.mdx b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/push/groupOnlinePushBefore.mdx new file mode 100644 index 0000000000..4fdc8bbae4 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/push/groupOnlinePushBefore.mdx @@ -0,0 +1,106 @@ +# Callback Before Group Message Push in Online Status + +## Function Description +Before sending messages to the client, the App business server can receive the request of sending messages through this callback. The business server can intercept, modify, or add additional push information to the message as needed. + +## Precautions +- To enable the callback, a callback URL must be configured, and the switch corresponding to this callback protocol must be turned on. See the [Callback Instructions](../introduction) document for configuration methods. +- The direction of the callback is an HTTP/HTTPS POST request initiated by OpenIM Server to the App backend. +- After receiving the callback request, the App business server needs to respond within the timeout period. + +## Scenarios That May Trigger This Callback +- Group member leaves the group. +- Group member is removed from the group. +- Dissolution of the group. + +## Timing of the Callback +- Before OpenIM Server prepares to push messages to the client. + +## Interface Description + +### Request URL Example +In the following example, the callback URL configured by the App is `https://callbackurl`. +```plaintext +https://callbackurl?command=$CallbackCommand&contenttype=json +``` + +### Request Parameters Description + +| Parameter | Description | +|-------------------|--------------------------------------------------| +| https | Request protocol is HTTPS, and the method is POST| +| https://callbackurl| Callback URL | +| CallbackCommand | Fixed value: callbackBeforePushCommand | +| contenttype | Fixed value: JSON | + +### Header +| Header Name | Example Value | Mandatory | Type | Description | +|:-------------|:--------------|:----------|:-------|:-----------------------------------------| +| operationID | 1646445464564 | Required | string | operationID is used for global link tracking | + +### Request Packet Example +```json +{ + "callbackCommand": "callbackBeforePushCommand", + "platformID": 1, + "platform": "iOS", + "clientMsgID": "msg123", + "sendID": "user789", + "groupID": "group123", + "contentType": 1, + "sessionType": 2, + "atUserIDList": ["user101", "user102"], + "content": "Hello, this is a test message" +} +``` + +### Request Packet Fields Explanation + +| Field | Type | Description | +|------------------|---------|--------------------------------------------------| +| callbackCommand | string | Callback command, here it is the callback before message push | +| platformID | int | Platform ID (e.g., 1 for iOS, 2 for Android) | +| platform | string | Platform name (e.g., iOS, Android) | +| clientMsgID | string | Client message ID | +| sendID | string | Sender ID | +| groupID | string | Group ID (if the message is sent to a group) | +| contentType | int | ID of the message content type | +| sessionType | int | ID of the session type | +| atUserIDList | array | List of user IDs who are mentioned in the message| +| content | string | Content of the message being sent | + +## Response Packet Example + +### Allow Push +Allow the message to be pushed to the client. + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": "", + "userIDList": ["user123", "user456"], + "offlinePushInfo": { + "title": "New Message", + "desc": "You have a new message", + "ex": "Extra push info", + "iOSPushSound": "default", + "iOSBadgeCount": true, + "signalInfo": "Signal data" + } +} +``` + +## Response Packet Fields Explanation + +| Field | Type | Description | +|-----------------|------------------------------|-----------------------------------------------------------------------------------------------------------------| +| actionCode | 0 | Indicates whether the business system callback was executed correctly. `0` means the operation was successful. | +| errCode | 5001 | Indicates a custom error code, ranging between 5000-9999. Set when actionCode is not 0; set when nextCode is 1. | +| errMsg | "An error message" | Simple error message corresponding to the custom error code. | +| errDlt | "Detailed error information" | Detailed error information corresponding to the custom error code. | +| nextCode | 1 | Next step instruction, `1` indicates refusal to continue execution, set when actionCode is `0`. | +| userIDList | array | List of user IDs allowed to receive the message. | +| offlinePushInfo | object | Object of offline push information. | \ No newline at end of file From 67916f57e3da55da87e49d1441939f2564b5675e Mon Sep 17 00:00:00 2001 From: mo3et Date: Thu, 30 Oct 2025 16:36:38 +0800 Subject: [PATCH 2/3] fix link error. --- .../current/gettingStarted/dockerCompose.mdx | 2 +- .../current/gettingStarted/imSourceCodeDeployment.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.mdx b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.mdx index b3ef1f2054..ffab63e6c5 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.mdx +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.mdx @@ -108,7 +108,7 @@ Please refer to the [Quick Verification](./quickTestServer) document. ## 4. Admin Panel and Monitoring System -Please refer to the [Admin Panel and Monitoring System](./admin) document. +Please refer to the Admin Panel and Monitoring System document. --- diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.mdx b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.mdx index 9a84210cbb..b115ed43ca 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.mdx +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.mdx @@ -196,7 +196,7 @@ Please refer to the [Quick Verification](./quickTestServer) document ## 5. Admin Panel and Monitoring System -Please refer to the [Admin Panel and Monitoring System](./admin) document. +Please refer to the Admin Panel and Monitoring System document. --- From 0a32de87bff658c2fd2b6bcbaac2090d0e6384da Mon Sep 17 00:00:00 2001 From: mo3et Date: Fri, 31 Oct 2025 16:40:19 +0800 Subject: [PATCH 3/3] feat: add conversation module in webhook docs. --- .../webhooks/conversations/_category_.json | 5 + .../createGroupChatConversationsAfter.mdx | 100 ++++++++++++++++ .../createGroupChatConversationsBefore.mdx | 110 ++++++++++++++++++ .../createSingleChatConversationsAfter.mdx | 100 ++++++++++++++++ .../createSingleChatConversationsBefore.mdx | 110 ++++++++++++++++++ 5 files changed, 425 insertions(+) create mode 100644 docs/restapi/webhooks/conversations/_category_.json create mode 100644 docs/restapi/webhooks/conversations/createGroupChatConversationsAfter.mdx create mode 100644 docs/restapi/webhooks/conversations/createGroupChatConversationsBefore.mdx create mode 100644 docs/restapi/webhooks/conversations/createSingleChatConversationsAfter.mdx create mode 100644 docs/restapi/webhooks/conversations/createSingleChatConversationsBefore.mdx diff --git a/docs/restapi/webhooks/conversations/_category_.json b/docs/restapi/webhooks/conversations/_category_.json new file mode 100644 index 0000000000..2bf6a60875 --- /dev/null +++ b/docs/restapi/webhooks/conversations/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "会话相关回调", + "collapsible": true, + "collapsed": true +} diff --git a/docs/restapi/webhooks/conversations/createGroupChatConversationsAfter.mdx b/docs/restapi/webhooks/conversations/createGroupChatConversationsAfter.mdx new file mode 100644 index 0000000000..9dc8e2dbd2 --- /dev/null +++ b/docs/restapi/webhooks/conversations/createGroupChatConversationsAfter.mdx @@ -0,0 +1,100 @@ +--- +title: 创建群聊会话后的回调 +hide_title: true +--- + +# 创建群聊会话后的回调 + +## 功能说明 + +App 业务服务端可以通过该回调实时对用户的单聊消息进行操作，如： + +- 对创建群聊会话进行实时记录（记录日志或同步到其他系统）。 + +## 注意事项 + +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- APP 业务服务端需在超时时间内响应此请求。 + +## 可能触发该回调的场景 + +- App 用户通过客户端创建群聊会话。 +- App 管理员通过 REST API 创建群聊会话 + +## 回调发生时机 + +- OpenIMServer 收到用户创建群聊会话消息，并将该消息下发给目标用户之后。 + +## 接口说明 + +### 请求 URL 示例 + +此处`CallbackCommand`为：`callbackAfterSendSingleMsgCommand` + +```plaintext +{WEBHOOK_ADDRESS}/callbackAfterSendSingleMsgCommand?contenttype=json +``` + + +### 请求包示例 + +```json +{ + "callbackCommand": "callbackAfterCreateSingleChatConversationsCommand", + "ownerUserId": "123228123", + "conversationId": "sg_123421231", + "conversationType": 3, + "groupId": "123421231", + "recvMsgOpt": 0, + "isPinned": false, + "isPrivateChat": false, + "burnDuration": 0, + "groupAtType": 0, + "attachedInfo": "", + "ex": "Extra conversation data" +} +``` + +### 请求包字段说明 + +| 对象 | 类型 | 描述 | +| ---------------- | ------- | ------------------------------------------------------------------------- | +| callbackCommand | string | 回调命令，这里是创建群聊会话后的回调 | +| ownerUserId | string | 会话的拥有者用户 Id | +| conversationId | string | 会话 Id | +| conversationType | int | 会话类型，1 为单聊，3 为群聊 | +| groupId | string | 会话群组 Id，当会话类型为 3 时，此字段生效 | +| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 | +| isPinned | boolean | 会话是否置顶 | +| isPrivateChat | boolean | 是否开启阅后即焚 | +| burnDuration | int | 阅后即焚消息持续时间 | +| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 | +| attachedInfo | string | openIM 使用的拓展字段 | +| ex | string | 用户使用的拓展字段 | + +## 应答包示例 + +### 成功响应 + +App 业务服务端同步数据后，发送回调应答包 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + +## 应答包字段说明 + +| 字段 | 值 | 说明 | +| ---------- | ---------------------------- | --------------------------------------------------------------- | +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 0 | 表示自定义错误码，此处填 0 代表忽略回调结果。 | +| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 | +| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 | +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 | diff --git a/docs/restapi/webhooks/conversations/createGroupChatConversationsBefore.mdx b/docs/restapi/webhooks/conversations/createGroupChatConversationsBefore.mdx new file mode 100644 index 0000000000..b944d7a048 --- /dev/null +++ b/docs/restapi/webhooks/conversations/createGroupChatConversationsBefore.mdx @@ -0,0 +1,110 @@ +--- +title: 创建群聊对话前的回调 +hide_title: true +--- + +# 在创建群聊对话前的回调 + +## 功能说明 + +App 业务服务端可以通过该回调实时对用户的群聊对话创建进行操作，如：对发群聊对话创建进行实时记录、允许创建群聊对话。 + +## 注意事项 + +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- APP 业务服务端需在超时时间内响应此请求。 + +## 可能触发该回调的场景 + +- App 用户通过客户端创建群聊对话。 + +## 回调发生时机 + +- OpenIMServer 收到用户创建群聊对话之后、将该信息下发给目标用户之前。 + +## 接口说明 + +### 请求 URL 示例 + +此处`CallbackCommand`为：`callbackBeforeCreateSingleChatConversationsCommand` + +```plaintext +{WEBHOOK_ADDRESS}/callbackBeforeCreateSingleChatConversationsCommand?contenttype=json +``` + +### 请求包示例 + +```json +{ + "callbackCommand": "callbackBeforeCreateSingleChatConversationsCommand", + "ownerUserId": "123228123", + "conversationId": "sg_215808001", + "conversationType": 3, + "groupId": "215808001", + "recvMsgOpt": 0, + "isPinned": false, + "isPrivateChat": false, + "burnDuration": 0, + "groupAtType": 0, + "attachedInfo": "", + "ex": "Extra conversation data" +} +``` + +### 请求包字段说明 + +| 对象 | 类型 | 描述 | +| ---------------- | ------- | ------------------------------------------------------------------------- | +| callbackCommand | string | 回调命令，这里是创建群聊对话前的回调 | +| ownerUserId | string | 会话的拥有者用户 Id | +| conversationId | string | 会话 Id | +| conversationType | int | 会话类型，1 为单聊，3 为群聊 | +| groupId | string | 会话群组 Id，当会话类型为 3 时，此字段生效 | +| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 | +| isPinned | boolean | 会话是否置顶 | +| isPrivateChat | boolean | 是否开启阅后即焚 | +| burnDuration | int | 阅后即焚消息持续时间 | +| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 | +| attachedInfo | string | openIM 使用的拓展字段 | +| ex | string | 用户使用的拓展字段 | + +## 应答包示例 + +### 允许创建 + +允许创建群聊对话。 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": "", + "recvMsgOpt": 1, + "isPinned": true, + "isPrivateChat": false, + "burnDuration": 30, + "groupAtType": 0, + "attachedInfo": "Modified attached info", + "ex": "Modified extra data" +} +``` + +## 应答包字段说明 + +| 字段 | 值 | 说明 | +| ------------- | ---------- | --------------------------------------------------------------------------------------------------- | +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 5001 | 表示自定义错误码，范围在 5000-9999 之间。在 actionCode 不等于 0 时设置；在 nextCode 等于 1 时设置。 | +| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 | +| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 | +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 | +| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 | +| isPinned | boolean | 会话是否置顶 | +| isPrivateChat | boolean | 是否开启阅后即焚 | +| burnDuration | int | 阅后即焚消息持续时间 | +| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 | +| attachedInfo | string | openIM 使用的拓展字段 | +| ex | string | 用户使用的拓展字段 | diff --git a/docs/restapi/webhooks/conversations/createSingleChatConversationsAfter.mdx b/docs/restapi/webhooks/conversations/createSingleChatConversationsAfter.mdx new file mode 100644 index 0000000000..7e2bffccb4 --- /dev/null +++ b/docs/restapi/webhooks/conversations/createSingleChatConversationsAfter.mdx @@ -0,0 +1,100 @@ +--- +title: 创建单聊会话后的回调 +hide_title: true +--- + +# 创建单聊会话后的回调 + +## 功能说明 + +App 业务服务端可以通过该回调实时对用户的单聊消息进行操作，如： + +- 对创建单聊会话进行实时记录（记录日志或同步到其他系统）。 + +## 注意事项 + +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- APP 业务服务端需在超时时间内响应此请求。 + +## 可能触发该回调的场景 + +- App 用户通过客户端创建单聊会话。 +- App 管理员通过 REST API 创建单聊会话 + +## 回调发生时机 + +- OpenIMServer 收到用户创建单聊会话消息，并将该消息下发给目标用户之后。 + +## 接口说明 + +### 请求 URL 示例 + +此处`CallbackCommand`为：`callbackAfterSendSingleMsgCommand` + +```plaintext +{WEBHOOK_ADDRESS}/callbackAfterSendSingleMsgCommand?contenttype=json +``` + + +### 请求包示例 + +```json +{ + "callbackCommand": "callbackAfterCreateSingleChatConversationsCommand", + "ownerUserId": "123228123", + "conversationId": "si_123228123_622925731", + "conversationType": 1, + "userId": "622925731", + "recvMsgOpt": 0, + "isPinned": false, + "isPrivateChat": false, + "burnDuration": 0, + "groupAtType": 0, + "attachedInfo": "", + "ex": "Extra conversation data" +} +``` + +### 请求包字段说明 + +| 对象 | 类型 | 描述 | +| ---------------- | ------- | ------------------------------------------------------------------------- | +| callbackCommand | string | 回调命令，这里是创建单聊会话后的回调 | +| ownerUserId | string | 会话的拥有者用户 Id | +| conversationId | string | 会话 Id | +| conversationType | int | 会话类型，1 为单聊，3 为群聊 | +| userId | string | 会话用户 Id，当会话类型为 1 时，此字段生效 | +| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 | +| isPinned | boolean | 会话是否置顶 | +| isPrivateChat | boolean | 是否开启阅后即焚 | +| burnDuration | int | 阅后即焚消息持续时间 | +| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 | +| attachedInfo | string | openIM 使用的拓展字段 | +| ex | string | 用户使用的拓展字段 | + +## 应答包示例 + +### 成功响应 + +App 业务服务端同步数据后，发送回调应答包 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": 0 +} +``` + +## 应答包字段说明 + +| 字段 | 值 | 说明 | +| ---------- | ---------------------------- | --------------------------------------------------------------- | +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 0 | 表示自定义错误码，此处填 0 代表忽略回调结果。 | +| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 | +| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 | +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 | diff --git a/docs/restapi/webhooks/conversations/createSingleChatConversationsBefore.mdx b/docs/restapi/webhooks/conversations/createSingleChatConversationsBefore.mdx new file mode 100644 index 0000000000..5aa96b08d6 --- /dev/null +++ b/docs/restapi/webhooks/conversations/createSingleChatConversationsBefore.mdx @@ -0,0 +1,110 @@ +--- +title: 创建单聊会话前的回调 +hide_title: true +--- + +# 在创建单聊会话前的回调 + +## 功能说明 + +App 业务服务端可以通过该回调实时对用户的单聊会话创建进行操作，如：对发单聊会话创建进行实时记录、允许创建单聊会话。 + +## 注意事项 + +- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。 +- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。 +- APP 业务服务端需在超时时间内响应此请求。 + +## 可能触发该回调的场景 + +- App 用户通过客户端创建单聊会话。 + +## 回调发生时机 + +- OpenIMServer 收到用户创建单聊会话之后、将该信息下发给目标用户之前。 + +## 接口说明 + +### 请求 URL 示例 + +此处`CallbackCommand`为：`callbackBeforeCreateSingleChatConversationsCommand` + +```plaintext +{WEBHOOK_ADDRESS}/callbackBeforeCreateSingleChatConversationsCommand?contenttype=json +``` + +### 请求包示例 + +```json +{ + "callbackCommand": "callbackBeforeCreateSingleChatConversationsCommand", + "ownerUserId": "123228123", + "conversationId": "si_123228123_622925731", + "conversationType": 1, + "userId": "622925731", + "recvMsgOpt": 0, + "isPinned": false, + "isPrivateChat": false, + "burnDuration": 0, + "groupAtType": 0, + "attachedInfo": "", + "ex": "Extra conversation data" +} +``` + +### 请求包字段说明 + +| 对象 | 类型 | 描述 | +| ---------------- | ------- | ------------------------------------------------------------------------- | +| callbackCommand | string | 回调命令，这里是创建单聊会话前的回调 | +| ownerUserId | string | 会话的拥有者用户 Id | +| conversationId | string | 会话 Id | +| conversationType | int | 会话类型，1 为单聊，3 为群聊 | +| userId | string | 会话用户 Id，当会话类型为 1 时，此字段生效 | +| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 | +| isPinned | boolean | 会话是否置顶 | +| isPrivateChat | boolean | 是否开启阅后即焚 | +| burnDuration | int | 阅后即焚消息持续时间 | +| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 | +| attachedInfo | string | openIM 使用的拓展字段 | +| ex | string | 用户使用的拓展字段 | + +## 应答包示例 + +### 允许创建 + +允许创建单聊会话。 + +```json +{ + "actionCode": 0, + "errCode": 0, + "errMsg": "", + "errDlt": "", + "nextCode": "", + "recvMsgOpt": 1, + "isPinned": true, + "isPrivateChat": false, + "burnDuration": 30, + "groupAtType": 0, + "attachedInfo": "Modified attached info", + "ex": "Modified extra data" +} +``` + +## 应答包字段说明 + +| 字段 | 值 | 说明 | +| ------------- | ---------- | --------------------------------------------------------------------------------------------------- | +| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 | +| errCode | 5001 | 表示自定义错误码，范围在 5000-9999 之间。在 actionCode 不等于 0 时设置；在 nextCode 等于 1 时设置。 | +| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 | +| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 | +| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 | +| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 | +| isPinned | boolean | 会话是否置顶 | +| isPrivateChat | boolean | 是否开启阅后即焚 | +| burnDuration | int | 阅后即焚消息持续时间 | +| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 | +| attachedInfo | string | openIM 使用的拓展字段 | +| ex | string | 用户使用的拓展字段 |