Skip to content

Commit a92633b

Browse files
mo3etmo3et
authored
docs: update user and group management API documentation (#156)
1 parent e0f27b1 commit a92633b

File tree

7 files changed

+364
-3
lines changed

7 files changed

+364
-3
lines changed

‎docs/restapi/apis/userManagement/updateUserInfoEx.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ hide_title: true
1111
</center>
1212

1313
### 简要描述
14-
- 修改用户的头像、昵称。
14+
- 修改用户的头像、昵称。（如果使用此接口，请使用 **[更新用户信息Ex之前的回调](docs/restapi/webhooks/user/updateUserInfoExBefore.mdx)** 和 **[更新用户信息Ex之后的回调](docs/restapi/webhooks/user/updateUserInfoExAfter.mdx)**。）
1515
### 请求方式
1616
- `post`
1717
### 请求URL

‎docs/restapi/webhooks/user/updateUserInfoExAfter.mdx‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: 更新用户信息Ex之后的回调
3+
hide_title: true
4+
---
5+
6+
# 更新用户信息Ex之后的回调
7+
8+
## 功能说明
9+
App 业务服务端可以通过该回调获取用户更新个人信息后的结果，App 后台可以据此进行数据同步等操作。
10+
11+
## 注意事项
12+
- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。
13+
- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
14+
- APP 业务服务端需在超时时间内响应此请求。
15+
16+
## 可能触发该回调的场景
17+
- App 用户通过客户端更新个人信息。
18+
- App 管理员通过 REST API 更新用户信息。
19+
20+
## 回调发生时机
21+
- OpenIMServer 处理完用户信息更新请求之后。
22+
23+
## 接口说明
24+
25+
### 请求 URL 示例
26+
以下示例中 App 配置的回调 URL 为 `http://www.example.com/callbackCommand?contenttype=json`。
27+
```plaintext
28+
http://www.example.com/callbackAfterUpdateUserInfoCommand?contenttype=json
29+
```
30+
31+
### 请求参数说明
32+
33+
| 参数 | 说明 |
34+
|-----------------|-----------------------------------------------|
35+
| http | 请求协议为 HTTP，请求方式为 POST |
36+
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
37+
| CallbackCommand | 此处为：callbackAfterUpdateUserInfoCommand |
38+
| contenttype | 固定值为：JSON |
39+
40+
### Header
41+
| header名 | 示例值 | 选填 | 类型 | 说明 |
42+
|:------------|:--------------|:----|--------|---------------------|
43+
| operationID | 1646445464564 | 必填 | string | operationID用于全局链路追踪 |
44+
45+
### 请求包示例
46+
```json
47+
{
48+
"callbackCommand": "callbackAfterUpdateUserInfoCommand",
49+
"userID": "user123",
50+
"nickName": "John Doe",
51+
"faceURL": "http://example.com/path/to/face/image.png",
52+
"ex": "Extra data"
53+
}
54+
```
55+
56+
### 请求包字段说明
57+
58+
| 字段 | 类型 | 描述 |
59+
|----------------|---------|---------------------------------|
60+
| callbackCommand | string | 回调命令，这里是更新用户信息之后的回调 |
61+
| userID | string | 用户的唯一标识符 |
62+
| nickName | StringValue | 用户的昵称 |
63+
| faceURL | StringValue | 用户头像的URL |
64+
| ex | StringValue | 额外的数据字段 |
65+
66+
## 应答包示例
67+
App 后台同步数据后，发送回调应答包。
68+
69+
```json
70+
{
71+
"actionCode": 0,
72+
"errCode": 0,
73+
"errMsg": "Success",
74+
"errDlt": "",
75+
"nextCode": 1
76+
}
77+
78+
```
79+
80+
81+
82+
## 应答包字段说明
83+
84+
| 字段 | 值 | 说明 |
85+
|-------------|------------------------------|------------------------------------------|
86+
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
87+
| errCode | 0 | 表示自定义错误码，此处填0代表忽略回调结果。|
88+
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。|
89+
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。|
90+
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode等于`0`时设置。|

‎docs/restapi/webhooks/user/updateUserInfoExBefore.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: 更新用户信息Ex之前的回调
3+
hide_title: true
4+
---
5+
6+
# 更新用户信息Ex之前的回调
7+
8+
## 功能说明
9+
App 业务服务端可以通过该回调获取用户更新个人信息的请求，或对请求做修改和干预。
10+
11+
## 注意事项
12+
- 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 [回调说明](../introduction) 文档。
13+
- 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
14+
- APP 业务服务端需在超时时间内响应此请求。
15+
16+
## 可能触发该回调的场景
17+
- App 用户通过客户端更新个人信息。
18+
- App 管理员通过 REST API 更新用户信息。:
19+
20+
21+
## 回调发生时机
22+
- OpenIMServer 准备更新用户信息之前。
23+
24+
## 接口说明
25+
26+
### 请求 URL 示例
27+
以下示例中 App 配置的回调 URL 为 `http://www.example.com/callbackCommand?contenttype=json`。
28+
```plaintext
29+
http://www.example.com/callbackBeforeUpdateUserInfoExCommand?contenttype=json
30+
```
31+
32+
### 请求参数说明
33+
34+
| 参数 | 说明 |
35+
|-----------------|-----------------------------------------------|
36+
| http | 请求协议为 HTTP，请求方式为 POST |
37+
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
38+
| CallbackCommand | callbackBeforeUpdateUserInfoExCommand |
39+
| contenttype | 固定值为：JSON |
40+
41+
### Header
42+
| header名 | 示例值 | 选填 | 类型 | 说明 |
43+
|:------------|:--------------|:----|--------|---------------------|
44+
| operationID | 1646445464564 | 必填 | string | operationID用于全局链路追踪 |
45+
46+
47+
### 请求包示例
48+
```json
49+
{
50+
"callbackCommand": "callbackBeforeUpdateUserInfoExCommand",
51+
"userID": "user123",
52+
"nickName": "John Doe",
53+
"faceURL": "http://example.com/path/to/face/image.png",
54+
"ex": "Extra data"
55+
}
56+
```
57+
58+
### 请求包字段说明
59+
60+
| 字段 | 类型 | 描述 |
61+
|----------------|---------|---------------------------------|
62+
| callbackCommand | string | 回调命令，这里是更新用户信息之前的回调 |
63+
| userID | string | 用户的唯一标识符 |
64+
| nickName | StringValue | 用户的昵称 |
65+
| faceURL | StringValue | 用户头像的URL |
66+
| ex | StringValue | 额外的数据字段 |
67+
68+
## 应答包示例
69+
70+
### 允许更新
71+
允许用户更新信息。
72+
73+
```json
74+
{
75+
"actionCode": 0,
76+
"errCode": 0,
77+
"errMsg": "Success",
78+
"errDlt": "",
79+
"nextCode": "0",
80+
"nickName": "John Doe Updated",
81+
"faceURL": "http://example.com/new/face/image.png",
82+
"ex": "Updated extra data"
83+
}
84+
```
85+
86+
## 应答包字段说明
87+
88+
| 字段 | 值 | 说明 |
89+
|------------|------------------------------|-------------------------------------------------------------------|
90+
| actionCode | 0 | 表示业务系统的回调是否正确执行。`0`表示操作成功。 |
91+
| errCode | 5001 | 表示自定义错误码，范围在5000-9999之间。在 actionCode 不等于0时设置；在 nextCode 等于1时设置。|
92+
| errMsg | "An error message" | 自定义错误码对应的简单错误信息。 |
93+
| errDlt | "Detailed error information" | 自定义错误码对应的详细错误信息。 |
94+
| nextCode | 1 | 下一步执行指令，`1`表示拒绝继续执行，actionCode 等于`0`时设置。 |
95+
| nickName | StringValue | 用户的昵称 |
96+
| faceURL | StringValue | 用户头像的URL |
97+
| ex | StringValue | 额外的数据字段 |

‎i18n/en/docusaurus-plugin-content-docs-restapi/current/apis/groupManagement/setGroupInfoEX.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ hide_title: true
1212

1313
### Brief description
1414

15-
- Modify group information. If you use this interface, (please use [setGroupInfoEXBefore](/restapi/webhooks/group/setGroupInfoEXBefore) and [setGroupInfoEXAfter](/restapi/webhooks/group/setGroupInfoEXAfter)).
15+
- Modify group information. (If you use this interface, please use [setGroupInfoEXBefore](/restapi/webhooks/group/setGroupInfoEXBefore) and [setGroupInfoEXAfter](/restapi/webhooks/group/setGroupInfoEXAfter)).
1616

1717
### Request method
1818
- `post`

‎i18n/en/docusaurus-plugin-content-docs-restapi/current/apis/userManagement/updateUserInfoEx.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ hide_title: true
1313
</center>
1414

1515
### Brief Description
16-
- Modify user's avatar and nickname.
16+
- Modify user's avatar and nickname. (If you use this interface, please use [updateUserInfoExBefore](/restapi/webhooks/user/updateUserInfoExBefore) and [updateUserInfoExAfter](/restapi/webhooks/user/updateUserInfoExAfter)).
1717

1818
### Request Method
1919
- `POST`

‎i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/user/updateUserInfoExAfter.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Callback After Updating User Information Ex
2+
3+
## Function Description
4+
The App business server can use this callback to get the results after a user updates their personal information. The backend can use this information for data synchronization and other operations.
5+
6+
## Precautions
7+
- To enable the callback, it is necessary to configure the callback URL and activate the corresponding switch for this callback protocol. Configuration methods can be found in the [Callback Explanation](../introduction) document.
8+
- The direction of the callback is an HTTP/HTTPS POST request initiated by OpenIMServer to the App backend.
9+
- After receiving the callback request, the App business server must verify whether the command parameter in the request URL is its SDKNAME parameter.
10+
- The APP business server must respond to this request within the timeout period.
11+
12+
## Scenarios That May Trigger This Callback
13+
- App users update their personal information through the client.
14+
- App administrators update user information through the REST API.
15+
16+
## Timing of the Callback
17+
- After OpenIMServer has processed the user information update request.
18+
19+
## Interface Description
20+
21+
### Request URL Example
22+
In the following example, the callback URL configured by the App is `https://callbackurl`.
23+
```plaintext
24+
https://callbackurl?command=$CallbackCommand&contenttype=json
25+
```
26+
27+
### Request Parameter Description
28+
29+
| Parameter | Description |
30+
|----------------------|------------------------------------------------------|
31+
| https | Request protocol is HTTPS, method is POST |
32+
| https://callbackurl | Callback URL |
33+
| CallbackCommand | Fixed value: callbackAfterUpdateUserInfoCommand |
34+
| contenttype | Fixed value: JSON |
35+
36+
### Header
37+
| Header Name | Example Value | Mandatory | Type | Description |
38+
|-------------|---------------|-----------|--------|-------------------------------------|
39+
| operationID | 1646445464564 | Required | string | operationID for global link tracing |
40+
41+
### Request Packet Example
42+
```json
43+
{
44+
"callbackCommand": "callbackAfterUpdateUserInfoCommand",
45+
"userID": "user123",
46+
"nickName": "John Doe",
47+
"faceURL": "http://example.com/path/to/face/image.png",
48+
"ex": "Extra data"
49+
}
50+
```
51+
52+
### Request Packet Field Explanation
53+
54+
| Field | Type | Description |
55+
|-----------------|---------|-------------------------------------------|
56+
| callbackCommand | string | Callback command, here for after updating user information |
57+
| userID | string | The unique identifier of the user |
58+
| nickName | string | The nickname of the user |
59+
| faceURL | string | URL of the user's avatar |
60+
| ex | string | Additional data fields |
61+
62+
## Response Packet Example
63+
The App backend sends a callback response packet after syncing data.
64+
65+
```json
66+
{
67+
"actionCode": 0,
68+
"errCode": 0,
69+
"errMsg": "Success",
70+
"errDlt": "",
71+
"nextCode": 1
72+
}
73+
```
74+
75+
## Response Packet Field Explanation
76+
77+
| Field | Value | Description |
78+
|------------|--------|----------------------------------------------------------|
79+
| actionCode | 0 | Indicates if the business system's callback was executed correctly. `0` means the operation was successful. |
80+
| errCode | 0 | Custom error code, here 0 means ignore the callback result. |
81+
| errMsg | "An error message" | Simple error message corresponding to the custom error code. |
82+
| errDlt | "Detailed error information" | Detailed error information corresponding to the custom error code. |
83+
| nextCode | 1 | Next step instruction, `1` means to refuse to continue executing, set when actionCode is `0`. |

‎i18n/en/docusaurus-plugin-content-docs-restapi/current/webhooks/user/updateUserInfoExBefore.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Callback Before Updating User Information Ex
2+
3+
## Function Description
4+
The App business server can use this callback to receive requests from users to update their personal information. Additionally, the business server can modify and intervene in the request.
5+
6+
## Precautions
7+
- To enable the callback, it is necessary to configure the callback URL and activate the corresponding switch for this callback protocol. Configuration methods can be found in the [Callback Explanation](../introduction) document.
8+
- The direction of the callback is an HTTP/HTTPS POST request initiated by OpenIMServer to the App backend.
9+
- After receiving the callback request, the App business server must verify whether the command parameter in the request URL is its SDKNAME parameter.
10+
- The APP business server must respond to this request within the timeout period.
11+
12+
## Scenarios That May Trigger This Callback
13+
- App users update their personal information through the client.
14+
- App administrators update user information through the REST API.
15+
16+
## Timing of the Callback
17+
- Before OpenIMServer prepares to update user information.
18+
19+
## Interface Description
20+
21+
### Request URL Example
22+
In the following example, the callback URL configured by the App is `https://callbackurl`.
23+
```plaintext
24+
https://callbackurl?command=$CallbackCommand&contenttype=json
25+
```
26+
27+
### Request Parameter Description
28+
29+
| Parameter | Description |
30+
|----------------------|------------------------------------------------------|
31+
| https | Request protocol is HTTPS, method is POST |
32+
| https://callbackurl | Callback URL |
33+
| CallbackCommand | Fixed value: callbackBeforeUpdateUserInfoExCommand |
34+
| contenttype | Fixed value: JSON |
35+
36+
### Header
37+
| Header Name | Example Value | Mandatory | Type | Description |
38+
|-------------|---------------|-----------|--------|-------------------------------------|
39+
| operationID | 1646445464564 | Required | string | operationID for global link tracing |
40+
41+
### Request Packet Example
42+
```json
43+
{
44+
"callbackCommand": "callbackBeforeUpdateUserInfoExCommand",
45+
"userID": "user123",
46+
"nickName": "John Doe",
47+
"faceURL": "http://example.com/path/to/face/image.png",
48+
"ex": "Extra data"
49+
}
50+
```
51+
52+
### Request Packet Field Explanation
53+
54+
| Field | Type | Description |
55+
|-----------------|---------|-------------------------------------------|
56+
| callbackCommand | string | Callback command, here for before updating user information |
57+
| userID | string | The unique identifier of the user |
58+
| nickName | StringValue | The nickname of the user |
59+
| faceURL | StringValue | URL of the user's avatar |
60+
| ex | StringValue | Additional data fields |
61+
62+
## Response Packet Example
63+
64+
### Allow Update
65+
Allows the user to update their information.
66+
67+
```json
68+
{
69+
"actionCode": 0,
70+
"errCode": 0,
71+
"errMsg": "Success",
72+
"errDlt": "",
73+
"nextCode": "0",
74+
"nickName": "John Doe Updated",
75+
"faceURL": "http://example.com/new/face/image.png",
76+
"ex": "Updated extra data"
77+
}
78+
```
79+
80+
## Response Packet Field Explanation
81+
82+
| Field | Value | Description |
83+
|------------|--------|----------------------------------------------------------|
84+
| actionCode | 0 | Indicates if the business system's callback was executed correctly. `0` means the operation was successful. |
85+
| errCode | 5001 | Custom error code, ranging between 5000-9999. Set when actionCode is not 0; set when nextCode is not 1. |
86+
| errMsg | "An error message" | Simple error message corresponding to the custom error code. |
87+
| errDlt | "Detailed error information" | Detailed error information corresponding to the custom error code. |
88+
| nextCode | 1 | Next step instruction, `1` means to refuse to continue executing, set when actionCode is `0`. |
89+
| nickName | StringValue | The nickname of the user. |
90+
| faceURL | StringValue | URL of the user's updated avatar. |
91+
| ex | StringValue | Updated additional data fields. |

0 commit comments

Comments
 (0)