Skip to content

Commit d86a23e

Browse files
mo3etmo3et
authored
feat: add webhook docs. (#284)
* feat: add webhook docs. * fix link error. * feat: add conversation module in webhook docs.
1 parent 8bf9788 commit d86a23e

15 files changed

Lines changed: 1219 additions & 2 deletions

‎docs/restapi/webhooks/conversations/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "会话相关回调",
3+
"collapsible": true,
4+
"collapsed": true
5+
}

‎docs/restapi/webhooks/conversations/createGroupChatConversationsAfter.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: 创建群聊会话后的回调
3+
hide_title: true
4+
---
5+
6+
# 创建群聊会话后的回调
7+
8+
## 功能说明
9+
10+
App 业务服务端可以通过该回调实时对用户的单聊消息进行操作，如：
11+
12+
- 对创建群聊会话进行实时记录（记录日志或同步到其他系统）。
13+
14+
## 注意事项
15+
16+
- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。
17+
- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
18+
- APP 业务服务端需在超时时间内响应此请求。
19+
20+
## 可能触发该回调的场景
21+
22+
- App 用户通过客户端创建群聊会话。
23+
- App 管理员通过 REST API 创建群聊会话
24+
25+
## 回调发生时机
26+
27+
- OpenIMServer 收到用户创建群聊会话消息，并将该消息下发给目标用户之后。
28+
29+
## 接口说明
30+
31+
### 请求 URL 示例
32+
33+
此处`CallbackCommand`为：`callbackAfterSendSingleMsgCommand`
34+
35+
```plaintext
36+
{WEBHOOK_ADDRESS}/callbackAfterSendSingleMsgCommand?contenttype=json
37+
```
38+
39+
40+
### 请求包示例
41+
42+
```json
43+
{
44+
"callbackCommand": "callbackAfterCreateSingleChatConversationsCommand",
45+
"ownerUserId": "123228123",
46+
"conversationId": "sg_123421231",
47+
"conversationType": 3,
48+
"groupId": "123421231",
49+
"recvMsgOpt": 0,
50+
"isPinned": false,
51+
"isPrivateChat": false,
52+
"burnDuration": 0,
53+
"groupAtType": 0,
54+
"attachedInfo": "",
55+
"ex": "Extra conversation data"
56+
}
57+
```
58+
59+
### 请求包字段说明
60+
61+
| 对象 | 类型 | 描述 |
62+
| ---------------- | ------- | ------------------------------------------------------------------------- |
63+
| callbackCommand | string | 回调命令，这里是创建群聊会话后的回调 |
64+
| ownerUserId | string | 会话的拥有者用户 Id |
65+
| conversationId | string | 会话 Id |
66+
| conversationType | int | 会话类型，1 为单聊，3 为群聊 |
67+
| groupId | string | 会话群组 Id，当会话类型为 3 时，此字段生效 |
68+
| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 |
69+
| isPinned | boolean | 会话是否置顶 |
70+
| isPrivateChat | boolean | 是否开启阅后即焚 |
71+
| burnDuration | int | 阅后即焚消息持续时间 |
72+
| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 |
73+
| attachedInfo | string | openIM 使用的拓展字段 |
74+
| ex | string | 用户使用的拓展字段 |
75+
76+
## 应答包示例
77+
78+
### 成功响应
79+
80+
App 业务服务端同步数据后，发送回调应答包
81+
82+
```json
83+
{
84+
"actionCode": 0,
85+
"errCode": 0,
86+
"errMsg": "",
87+
"errDlt": "",
88+
"nextCode": 0
89+
}
90+
```
91+
92+
## 应答包字段说明
93+
94+
| 字段 | 值 | 说明 |
95+
| ---------- | ---------------------------- | --------------------------------------------------------------- |
96+
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
97+
| errCode | 0 | 表示自定义错误码，此处填 0 代表忽略回调结果。 |
98+
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 |
99+
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 |
100+
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 |

‎docs/restapi/webhooks/conversations/createGroupChatConversationsBefore.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: 创建群聊对话前的回调
3+
hide_title: true
4+
---
5+
6+
# 在创建群聊对话前的回调
7+
8+
## 功能说明
9+
10+
App 业务服务端可以通过该回调实时对用户的群聊对话创建进行操作，如：对发群聊对话创建进行实时记录、允许创建群聊对话。
11+
12+
## 注意事项
13+
14+
- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。
15+
- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
16+
- APP 业务服务端需在超时时间内响应此请求。
17+
18+
## 可能触发该回调的场景
19+
20+
- App 用户通过客户端创建群聊对话。
21+
22+
## 回调发生时机
23+
24+
- OpenIMServer 收到用户创建群聊对话之后、将该信息下发给目标用户之前。
25+
26+
## 接口说明
27+
28+
### 请求 URL 示例
29+
30+
此处`CallbackCommand`为：`callbackBeforeCreateSingleChatConversationsCommand`
31+
32+
```plaintext
33+
{WEBHOOK_ADDRESS}/callbackBeforeCreateSingleChatConversationsCommand?contenttype=json
34+
```
35+
36+
### 请求包示例
37+
38+
```json
39+
{
40+
"callbackCommand": "callbackBeforeCreateSingleChatConversationsCommand",
41+
"ownerUserId": "123228123",
42+
"conversationId": "sg_215808001",
43+
"conversationType": 3,
44+
"groupId": "215808001",
45+
"recvMsgOpt": 0,
46+
"isPinned": false,
47+
"isPrivateChat": false,
48+
"burnDuration": 0,
49+
"groupAtType": 0,
50+
"attachedInfo": "",
51+
"ex": "Extra conversation data"
52+
}
53+
```
54+
55+
### 请求包字段说明
56+
57+
| 对象 | 类型 | 描述 |
58+
| ---------------- | ------- | ------------------------------------------------------------------------- |
59+
| callbackCommand | string | 回调命令，这里是创建群聊对话前的回调 |
60+
| ownerUserId | string | 会话的拥有者用户 Id |
61+
| conversationId | string | 会话 Id |
62+
| conversationType | int | 会话类型，1 为单聊，3 为群聊 |
63+
| groupId | string | 会话群组 Id，当会话类型为 3 时，此字段生效 |
64+
| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 |
65+
| isPinned | boolean | 会话是否置顶 |
66+
| isPrivateChat | boolean | 是否开启阅后即焚 |
67+
| burnDuration | int | 阅后即焚消息持续时间 |
68+
| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 |
69+
| attachedInfo | string | openIM 使用的拓展字段 |
70+
| ex | string | 用户使用的拓展字段 |
71+
72+
## 应答包示例
73+
74+
### 允许创建
75+
76+
允许创建群聊对话。
77+
78+
```json
79+
{
80+
"actionCode": 0,
81+
"errCode": 0,
82+
"errMsg": "",
83+
"errDlt": "",
84+
"nextCode": "",
85+
"recvMsgOpt": 1,
86+
"isPinned": true,
87+
"isPrivateChat": false,
88+
"burnDuration": 30,
89+
"groupAtType": 0,
90+
"attachedInfo": "Modified attached info",
91+
"ex": "Modified extra data"
92+
}
93+
```
94+
95+
## 应答包字段说明
96+
97+
| 字段 | 值 | 说明 |
98+
| ------------- | ---------- | --------------------------------------------------------------------------------------------------- |
99+
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
100+
| errCode | 5001 | 表示自定义错误码，范围在 5000-9999 之间。在 actionCode 不等于 0 时设置；在 nextCode 等于 1 时设置。 |
101+
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 |
102+
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 |
103+
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 |
104+
| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 |
105+
| isPinned | boolean | 会话是否置顶 |
106+
| isPrivateChat | boolean | 是否开启阅后即焚 |
107+
| burnDuration | int | 阅后即焚消息持续时间 |
108+
| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 |
109+
| attachedInfo | string | openIM 使用的拓展字段 |
110+
| ex | string | 用户使用的拓展字段 |

‎docs/restapi/webhooks/conversations/createSingleChatConversationsAfter.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: 创建单聊会话后的回调
3+
hide_title: true
4+
---
5+
6+
# 创建单聊会话后的回调
7+
8+
## 功能说明
9+
10+
App 业务服务端可以通过该回调实时对用户的单聊消息进行操作，如：
11+
12+
- 对创建单聊会话进行实时记录（记录日志或同步到其他系统）。
13+
14+
## 注意事项
15+
16+
- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。
17+
- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
18+
- APP 业务服务端需在超时时间内响应此请求。
19+
20+
## 可能触发该回调的场景
21+
22+
- App 用户通过客户端创建单聊会话。
23+
- App 管理员通过 REST API 创建单聊会话
24+
25+
## 回调发生时机
26+
27+
- OpenIMServer 收到用户创建单聊会话消息，并将该消息下发给目标用户之后。
28+
29+
## 接口说明
30+
31+
### 请求 URL 示例
32+
33+
此处`CallbackCommand`为：`callbackAfterSendSingleMsgCommand`
34+
35+
```plaintext
36+
{WEBHOOK_ADDRESS}/callbackAfterSendSingleMsgCommand?contenttype=json
37+
```
38+
39+
40+
### 请求包示例
41+
42+
```json
43+
{
44+
"callbackCommand": "callbackAfterCreateSingleChatConversationsCommand",
45+
"ownerUserId": "123228123",
46+
"conversationId": "si_123228123_622925731",
47+
"conversationType": 1,
48+
"userId": "622925731",
49+
"recvMsgOpt": 0,
50+
"isPinned": false,
51+
"isPrivateChat": false,
52+
"burnDuration": 0,
53+
"groupAtType": 0,
54+
"attachedInfo": "",
55+
"ex": "Extra conversation data"
56+
}
57+
```
58+
59+
### 请求包字段说明
60+
61+
| 对象 | 类型 | 描述 |
62+
| ---------------- | ------- | ------------------------------------------------------------------------- |
63+
| callbackCommand | string | 回调命令，这里是创建单聊会话后的回调 |
64+
| ownerUserId | string | 会话的拥有者用户 Id |
65+
| conversationId | string | 会话 Id |
66+
| conversationType | int | 会话类型，1 为单聊，3 为群聊 |
67+
| userId | string | 会话用户 Id，当会话类型为 1 时，此字段生效 |
68+
| recvMsgOpt | int | 接收消息参数，0 为接收消息；1 为不接收消息；2 为接收消息但不提醒 |
69+
| isPinned | boolean | 会话是否置顶 |
70+
| isPrivateChat | boolean | 是否开启阅后即焚 |
71+
| burnDuration | int | 阅后即焚消息持续时间 |
72+
| groupAtType | int | 群会话公告强提示类型，群公告有人**@ownerUserID** , **@全体** 的特殊标识符 |
73+
| attachedInfo | string | openIM 使用的拓展字段 |
74+
| ex | string | 用户使用的拓展字段 |
75+
76+
## 应答包示例
77+
78+
### 成功响应
79+
80+
App 业务服务端同步数据后，发送回调应答包
81+
82+
```json
83+
{
84+
"actionCode": 0,
85+
"errCode": 0,
86+
"errMsg": "",
87+
"errDlt": "",
88+
"nextCode": 0
89+
}
90+
```
91+
92+
## 应答包字段说明
93+
94+
| 字段 | 值 | 说明 |
95+
| ---------- | ---------------------------- | --------------------------------------------------------------- |
96+
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
97+
| errCode | 0 | 表示自定义错误码，此处填 0 代表忽略回调结果。 |
98+
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 |
99+
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 |
100+
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 |

0 commit comments

Comments
 (0)