Skip to content

Commit ea9cf25

Browse files
mo3etmo3et
authored
docs: update webhook docs in user and relation. (#162)
1 parent 717da04 commit ea9cf25

22 files changed

Lines changed: 753 additions & 630 deletions

‎docs/restapi/introduction.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ OpenIM Server 提供了 **REST API** 供业务系统使用，以增强业务功
1717
> ⚠️ **注意**:
1818
> 请求 URL 中的 `{API_ADDRESS}` 为 OpenIM Server 部署的主机地址，如 `http://IP:10002`。
1919
>
20-
> 调用 **REST API** ，需要以 **APP 管理员** 身份进行，此服务由端口 `10002` 提供。所谓 **APP 管理员**，即有超级权限的用户。OpenIMServer 内置了一个 APP 管理员，它的 userID 为 imAdmin
20+
> 调用 **REST API** ，需要以 **APP 管理员** 身份进行，此服务由端口 `10002` 提供。所谓 **APP 管理员**，即有超级权限的用户。OpenIM Server 内置了一个 APP 管理员，它的 userID 为 imAdmin
2121
2222
在开始调用 API 之前，需首先使用 secret [获取管理员 token](./apis/authenticationManagement/getToken)
2323
，对于 [导入用户](./apis/userManagement/userRegister) 接口，也需要使用 secret 验证。

‎docs/restapi/webhooks/push/offlinePushBefore.mdx‎

Lines changed: 63 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -6,47 +6,55 @@ hide_title: true
66
# 离线状态下消息推送前的回调
77

88
## 功能说明
9+
910
在消息发送至客户端前，App 业务服务端可以通过该回调接收到发送消息的请求。业务服务端可以根据需要对消息进行拦截、修改或添加额外的推送信息。
1011

1112
## 注意事项
13+
1214
- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。
13-
- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
15+
- 回调的方向是 OpenIM Server 向 App 后台发起 HTTP/HTTPS POST 请求。
1416
- App 业务服务端在收到回调请求后，需在超时时间内做出响应。
1517

1618
## 可能触发该回调的场景
19+
1720
- 群成员退出群组。
1821
- 群成员被踢出群组。
1922
- 群组解散。
2023

2124
## 回调发生时机
25+
2226
- OpenIMServer 准备向客户端推送消息前。
2327

2428
## 接口说明
2529

2630
### 请求 URL 示例
31+
2732
以下示例中 App 配置的回调 URL 为 `http://www.example.com/callbackCommand?contenttype=json`。
33+
2834
```plaintext
29-
http://www.example.com/callbackBeforePushCommand?contenttype=json
35+
http://www.example.com/callbackBeforeOfflinePushCommand?contenttype=json
3036
```
3137

3238
### 请求参数说明
3339

34-
| 参数 | 说明 |
35-
|-----------------|-----------------------------------------------|
36-
| http | 请求协议为 HTTP，请求方式为 POST |
37-
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
38-
| CallbackCommand | 此处为：callbackBeforePushCommand |
39-
| contenttype | 固定值为：JSON |
40+
| 参数 | 说明 |
41+
| --------------- | ------------------------------------------------- |
42+
| http | 请求协议为 HTTP，请求方式为 POST |
43+
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
44+
| CallbackCommand | 此处为：callbackBeforeOfflinePushCommand |
45+
| contenttype | 固定值为：JSON |
4046

4147
### Header
42-
| header名 | 示例值 | 选填 | 类型 | 说明 |
43-
|:------------|:--------------|:----|--------|---------------------|
44-
| operationID | 1646445464564 | 必填 | string | operationID用于全局链路追踪 |
48+
49+
| header 名 | 示例值 | 选填 | 类型 | 说明 |
50+
| :---------- | :------------ | :--- | ------ | ---------------------------- |
51+
| operationID | 1646445464564 | 必填 | string | operationID 用于全局链路追踪 |
4552

4653
### 请求包示例
54+
4755
```json
4856
{
49-
"callbackCommand": "callbackBeforePushCommand",
57+
"callbackCommand": "callbackBeforeOfflinePushCommand",
5058
"platformID": 1,
5159
"platform": "iOS",
5260
"userIDList": ["user123", "user456"],
@@ -68,60 +76,59 @@ http://www.example.com/callbackBeforePushCommand?contenttype=json
6876

6977
### 请求包字段说明
7078

71-
| 字段 | 类型 | 描述 |
72-
|----------------|---------|------------------------------------------------|
73-
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
74-
| platformID | int | 平台ID（如 1 代表 iOS，2 代表 Android） |
75-
| platform | string | 平台名称（如 iOS、Android） |
76-
| userIDList | array | 用户ID列表，表示哪些用户将接收此消息 |
77-
| title | string | 推送消息的标题 |
78-
| desc | string | 推送消息的描述 |
79-
| ex | string | 额外的推送信息 |
80-
| iOSPushSound | string | iOS 推送时的声音设置 |
81-
| iOSBadgeCount | bool | iOS 推送时是否改变应用角标计数 |
82-
| signalInfo | string | 推送携带的附加信号信息 |
83-
| clientMsgID | string | 客户端消息ID |
84-
| sendID | string | 发送者的用户ID |
85-
| groupID | string | 群组ID，如果是群消息的话 |
86-
| contentType | int | 消息内容的类型 |
87-
| sessionType | int | 会话类型（如 1 代表单聊，2 代表群聊） |
88-
| atUserIDList | array | 被@的用户ID列表 |
89-
| content | string | 发送的消息内容 |
90-
91-
79+
| 字段 | 类型 | 描述 |
80+
| --------------- | ------ | ---------------------------------------- |
81+
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
82+
| platformID | int | 平台 ID（如 1 代表 iOS，2 代表 Android） |
83+
| platform | string | 平台名称（如 iOS、Android） |
84+
| userIDList | array | 用户 ID 列表，表示哪些用户将接收此消息 |
85+
| title | string | 推送消息的标题 |
86+
| desc | string | 推送消息的描述 |
87+
| ex | string | 额外的推送信息 |
88+
| iOSPushSound | string | iOS 推送时的声音设置 |
89+
| iOSBadgeCount | bool | iOS 推送时是否改变应用角标计数 |
90+
| signalInfo | string | 推送携带的附加信号信息 |
91+
| clientMsgID | string | 客户端消息 ID |
92+
| sendID | string | 发送者的用户 ID |
93+
| groupID | string | 群组 ID，如果是群消息的话 |
94+
| contentType | int | 消息内容的类型 |
95+
| sessionType | int | 会话类型（如 1 代表单聊，2 代表群聊） |
96+
| atUserIDList | array | 被@的用户 ID 列表 |
97+
| content | string | 发送的消息内容 |
9298

9399
## 应答包示例
94100

95101
### 允许推送
102+
96103
允许消息被推送到客户端。
97104

98105
```json
99106
{
100-
"actionCode": 0,
101-
"errCode": 0,
102-
"errMsg": "Success",
103-
"errDlt": "",
104-
"nextCode": "",
105-
"userIDList": ["user123", "user456"],
106-
"offlinePushInfo": {
107-
"title": "New Message",
108-
"desc": "You have a new message",
109-
"ex": "Extra push info",
110-
"iOSPushSound": "default",
111-
"iOSBadgeCount": true,
112-
"signalInfo": "Signal data"
113-
}
107+
"actionCode": 0,
108+
"errCode": 0,
109+
"errMsg": "Success",
110+
"errDlt": "",
111+
"nextCode": "",
112+
"userIDList": ["user123", "user456"],
113+
"offlinePushInfo": {
114+
"title": "New Message",
115+
"desc": "You have a new message",
116+
"ex": "Extra push info",
117+
"iOSPushSound": "default",
118+
"iOSBadgeCount": true,
119+
"signalInfo": "Signal data"
120+
}
114121
}
115122
```
116123

117124
## 应答包字段说明
118125

119-
| 字段 | 类型 | 描述 |
120-
|---------------|--------|-------------------------------------------------|
121-
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
122-
| errCode | 5001 | 表示自定义错误码，范围在5000-9999之间。在 actionCode 不等于0时设置；在 nextCode 等于1时设置。|
123-
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。|
124-
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。|
125-
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。|
126-
| userIDList | array | 用户ID列表，表示允许接收消息的用户。 |
127-
| offlinePushInfo | object | 离线推送信息对象。 |
126+
| 字段 | 类型 | 描述 |
127+
| --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
128+
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
129+
| errCode | 5001 | 表示自定义错误码，范围在 5000-9999 之间。在 actionCode 不等于 0 时设置；在 nextCode 等于 1 时设置。 |
130+
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 |
131+
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 |
132+
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 |
133+
| userIDList | array | 用户 ID 列表，表示允许接收消息的用户。 |
134+
| offlinePushInfo | object | 离线推送信息对象。 |

‎docs/restapi/webhooks/push/onlinePushBefore.mdx‎

Lines changed: 62 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -6,47 +6,55 @@ hide_title: true
66
# 在线状态下消息推送前的回调
77

88
## 功能说明
9+
910
在消息发送至客户端前，App 业务服务端可以通过该回调接收到发送消息的请求。业务服务端可以根据需要对消息进行拦截、修改或添加额外的推送信息。
1011

1112
## 注意事项
13+
1214
- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。
1315
- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
1416
- App 业务服务端在收到回调请求后，需在超时时间内做出响应。
1517

1618
## 可能触发该回调的场景
19+
1720
- 群成员退出群组。
1821
- 群成员被踢出群组。
1922
- 群组解散。
2023

2124
## 回调发生时机
25+
2226
- OpenIMServer 准备向客户端推送消息前。
2327

2428
## 接口说明
2529

2630
### 请求 URL 示例
31+
2732
以下示例中 App 配置的回调 URL 为 `http://www.example.com/callbackCommand?contenttype=json`。
33+
2834
```plaintext
29-
http://www.example.com/callbackBeforePushCommand?contenttype=json
35+
http://www.example.com/callbackBeforeOnlinePushCommand?contenttype=json
3036
```
3137

3238
### 请求参数说明
3339

34-
| 参数 | 说明 |
35-
|-----------------|-----------------------------------------------|
36-
| http | 请求协议为 HTTP，请求方式为 POST |
37-
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
38-
| CallbackCommand | 此处为：callbackBeforePushCommand |
39-
| contenttype | 固定值为：JSON |
40+
| 参数 | 说明 |
41+
| --------------- | ------------------------------------------------- |
42+
| http | 请求协议为 HTTP，请求方式为 POST |
43+
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
44+
| CallbackCommand | 此处为：callbackBeforeOnlinePushCommand |
45+
| contenttype | 固定值为：JSON |
4046

4147
### Header
42-
| header名 | 示例值 | 选填 | 类型 | 说明 |
43-
|:------------|:--------------|:----|--------|---------------------|
44-
| operationID | 1646445464564 | 必填 | string | operationID用于全局链路追踪 |
48+
49+
| header 名 | 示例值 | 选填 | 类型 | 说明 |
50+
| :---------- | :------------ | :--- | ------ | ---------------------------- |
51+
| operationID | 1646445464564 | 必填 | string | operationID 用于全局链路追踪 |
4552

4653
### 请求包示例
54+
4755
```json
4856
{
49-
"callbackCommand": "callbackBeforePushCommand",
57+
"callbackCommand": "callbackBeforeOnlinePushCommand",
5058
"platformID": 1,
5159
"platform": "iOS",
5260
"userIDList": ["user123", "user456"],
@@ -68,59 +76,59 @@ http://www.example.com/callbackBeforePushCommand?contenttype=json
6876

6977
### 请求包字段说明
7078

71-
| 字段 | 类型 | 描述 |
72-
|--------------|----------|--------------------------------------------------|
73-
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
74-
| platformID | int | 平台ID（如 1 代表 iOS，2 代表 Android） |
75-
| platform | string | 平台名称（如 iOS、Android） |
76-
| userIDList | array | 用户ID列表，表示哪些用户将接收此消息 |
77-
| title | string | 推送消息的标题 |
78-
| desc | string | 推送消息的描述或正文内容 |
79-
| ex | string | 额外的推送信息 |
80-
| iOSPushSound | string | iOS 设备上推送消息时使用的声音 |
81-
| iOSBadgeCount | boolean | 是否在iOS应用图标上显示未读消息数 |
82-
| signalInfo | string | 附加信号数据，用于传递额外信息 |
83-
| clientMsgID | string | 客户端消息ID |
84-
| sendID | string | 发送者ID |
85-
| groupID | string | 群组ID（如果消息是发送到群组的） |
86-
| contentType | int | 消息内容类型的ID |
87-
| sessionType | int | 会话类型的ID |
88-
| atUserIDList | array | 被@用户的ID列表 |
89-
| content | string | 发送的消息内容 |
90-
79+
| 字段 | 类型 | 描述 |
80+
| --------------- | ------- | ---------------------------------------- |
81+
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
82+
| platformID | int | 平台 ID（如 1 代表 iOS，2 代表 Android） |
83+
| platform | string | 平台名称（如 iOS、Android） |
84+
| userIDList | array | 用户 ID 列表，表示哪些用户将接收此消息 |
85+
| title | string | 推送消息的标题 |
86+
| desc | string | 推送消息的描述或正文内容 |
87+
| ex | string | 额外的推送信息 |
88+
| iOSPushSound | string | iOS 设备上推送消息时使用的声音 |
89+
| iOSBadgeCount | boolean | 是否在 iOS 应用图标上显示未读消息数 |
90+
| signalInfo | string | 附加信号数据，用于传递额外信息 |
91+
| clientMsgID | string | 客户端消息 ID |
92+
| sendID | string | 发送者 ID |
93+
| groupID | string | 群组 ID（如果消息是发送到群组的） |
94+
| contentType | int | 消息内容类型的 ID |
95+
| sessionType | int | 会话类型的 ID |
96+
| atUserIDList | array | 被@用户的 ID 列表 |
97+
| content | string | 发送的消息内容 |
9198

9299
## 应答包示例
93100

94101
### 允许推送
102+
95103
允许消息被推送到客户端。
96104

97105
```json
98106
{
99-
"actionCode": 0,
100-
"errCode": 0,
101-
"errMsg": "Success",
102-
"errDlt": "",
103-
"nextCode": "",
104-
"userIDList": ["user123", "user456"],
105-
"offlinePushInfo": {
106-
"title": "New Message",
107-
"desc": "You have a new message",
108-
"ex": "Extra push info",
109-
"iOSPushSound": "default",
110-
"iOSBadgeCount": true,
111-
"signalInfo": "Signal data"
112-
}
107+
"actionCode": 0,
108+
"errCode": 0,
109+
"errMsg": "Success",
110+
"errDlt": "",
111+
"nextCode": "",
112+
"userIDList": ["user123", "user456"],
113+
"offlinePushInfo": {
114+
"title": "New Message",
115+
"desc": "You have a new message",
116+
"ex": "Extra push info",
117+
"iOSPushSound": "default",
118+
"iOSBadgeCount": true,
119+
"signalInfo": "Signal data"
120+
}
113121
}
114122
```
115123

116124
## 应答包字段说明
117125

118-
| 字段 | 类型 | 描述 |
119-
|---------------|--------|-------------------------------------------------|
120-
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
121-
| errCode | 5001 | 表示自定义错误码，范围在5000-9999之间。在 actionCode 不等于0时设置；在 nextCode 等于1时设置。|
122-
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。|
123-
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。|
124-
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。|
125-
| userIDList | array | 用户ID列表，表示允许接收消息的用户。 |
126-
| offlinePushInfo | object | 离线推送信息对象。 |
126+
| 字段 | 类型 | 描述 |
127+
| --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
128+
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
129+
| errCode | 5001 | 表示自定义错误码，范围在 5000-9999 之间。在 actionCode 不等于 0 时设置；在 nextCode 等于 1 时设置。 |
130+
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 |
131+
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 |
132+
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 |
133+
| userIDList | array | 用户 ID 列表，表示允许接收消息的用户。 |
134+
| offlinePushInfo | object | 离线推送信息对象。 |

0 commit comments

Comments
 (0)