Skip to content

docs: update webhook docs in user and relation. #162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lgz5689 merged 2 commits into from
Sep 20, 2024
Merged

docs: update webhook docs in user and relation. #162

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6061778
update webhook docs in user and relation.
mo3et Sep 20, 2024
05ee985
docs: update OpenIM type.
mo3et Sep 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/restapi/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ OpenIM Server 提供了 **REST API** 供业务系统使用，以增强业务功
> ⚠️ **注意**:
> 请求 URL 中的 `{API_ADDRESS}` 为 OpenIM Server 部署的主机地址，如 `http://IP:10002`。
>
> 调用 **REST API** ，需要以 **APP 管理员** 身份进行，此服务由端口 `10002` 提供。所谓 **APP 管理员**，即有超级权限的用户。OpenIMServer 内置了一个 APP 管理员，它的 userID 为 imAdmin
> 调用 **REST API** ，需要以 **APP 管理员** 身份进行，此服务由端口 `10002` 提供。所谓 **APP 管理员**，即有超级权限的用户。OpenIM Server 内置了一个 APP 管理员，它的 userID 为 imAdmin

在开始调用 API 之前，需首先使用 secret [获取管理员 token](./apis/authenticationManagement/getToken)
，对于 [导入用户](./apis/userManagement/userRegister) 接口，也需要使用 secret 验证。
Expand Down
119 changes: 63 additions & 56 deletions docs/restapi/webhooks/push/offlinePushBefore.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,47 +6,55 @@ hide_title: true
# 离线状态下消息推送前的回调

## 功能说明

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

## 注意事项

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

## 可能触发该回调的场景

- 群成员退出群组。
- 群成员被踢出群组。
- 群组解散。

## 回调发生时机

- OpenIMServer 准备向客户端推送消息前。

## 接口说明

### 请求 URL 示例

以下示例中 App 配置的回调 URL 为 `http://www.example.com/callbackCommand?contenttype=json`。

```plaintext
http://www.example.com/callbackBeforePushCommand?contenttype=json
http://www.example.com/callbackBeforeOfflinePushCommand?contenttype=json
```

### 请求参数说明

| 参数 | 说明 |
|-----------------|-----------------------------------------------|
| http | 请求协议为 HTTP，请求方式为 POST |
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
| CallbackCommand | 此处为：callbackBeforePushCommand |
| contenttype | 固定值为：JSON |
| 参数 | 说明 |
| --------------- | ------------------------------------------------- |
| http | 请求协议为 HTTP，请求方式为 POST |
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
| CallbackCommand | 此处为：callbackBeforeOfflinePushCommand |
| contenttype | 固定值为：JSON |

### Header
| header名 | 示例值 | 选填 | 类型 | 说明 |
|:------------|:--------------|:----|--------|---------------------|
| operationID | 1646445464564 | 必填 | string | operationID用于全局链路追踪 |

| header 名 | 示例值 | 选填 | 类型 | 说明 |
| :---------- | :------------ | :--- | ------ | ---------------------------- |
| operationID | 1646445464564 | 必填 | string | operationID 用于全局链路追踪 |

### 请求包示例

```json
{
"callbackCommand": "callbackBeforePushCommand",
"callbackCommand": "callbackBeforeOfflinePushCommand",
"platformID": 1,
"platform": "iOS",
"userIDList": ["user123", "user456"],
Expand All @@ -68,60 +76,59 @@ http://www.example.com/callbackBeforePushCommand?contenttype=json

### 请求包字段说明

| 字段 | 类型 | 描述 |
|----------------|---------|------------------------------------------------|
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
| platformID | int | 平台ID（如 1 代表 iOS，2 代表 Android） |
| platform | string | 平台名称（如 iOS、Android） |
| userIDList | array | 用户ID列表，表示哪些用户将接收此消息 |
| title | string | 推送消息的标题 |
| desc | string | 推送消息的描述 |
| ex | string | 额外的推送信息 |
| iOSPushSound | string | iOS 推送时的声音设置 |
| iOSBadgeCount | bool | iOS 推送时是否改变应用角标计数 |
| signalInfo | string | 推送携带的附加信号信息 |
| clientMsgID | string | 客户端消息ID |
| sendID | string | 发送者的用户ID |
| groupID | string | 群组ID，如果是群消息的话 |
| contentType | int | 消息内容的类型 |
| sessionType | int | 会话类型（如 1 代表单聊，2 代表群聊） |
| atUserIDList | array | 被@的用户ID列表 |
| content | string | 发送的消息内容 |


| 字段 | 类型 | 描述 |
| --------------- | ------ | ---------------------------------------- |
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
| platformID | int | 平台 ID（如 1 代表 iOS，2 代表 Android） |
| platform | string | 平台名称（如 iOS、Android） |
| userIDList | array | 用户 ID 列表，表示哪些用户将接收此消息 |
| title | string | 推送消息的标题 |
| desc | string | 推送消息的描述 |
| ex | string | 额外的推送信息 |
| iOSPushSound | string | iOS 推送时的声音设置 |
| iOSBadgeCount | bool | iOS 推送时是否改变应用角标计数 |
| signalInfo | string | 推送携带的附加信号信息 |
| clientMsgID | string | 客户端消息 ID |
| sendID | string | 发送者的用户 ID |
| groupID | string | 群组 ID，如果是群消息的话 |
| contentType | int | 消息内容的类型 |
| sessionType | int | 会话类型（如 1 代表单聊，2 代表群聊） |
| atUserIDList | array | 被@的用户 ID 列表 |
| content | string | 发送的消息内容 |

## 应答包示例

### 允许推送

允许消息被推送到客户端。

```json
{
"actionCode": 0,
"errCode": 0,
"errMsg": "Success",
"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,
"errCode": 0,
"errMsg": "Success",
"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 | 离线推送信息对象。 |
| 字段 | 类型 | 描述 |
| --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| 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 | 离线推送信息对象。 |
116 changes: 62 additions & 54 deletions docs/restapi/webhooks/push/onlinePushBefore.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,47 +6,55 @@ hide_title: true
# 在线状态下消息推送前的回调

## 功能说明

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

## 注意事项

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

## 可能触发该回调的场景

- 群成员退出群组。
- 群成员被踢出群组。
- 群组解散。

## 回调发生时机

- OpenIMServer 准备向客户端推送消息前。

## 接口说明

### 请求 URL 示例

以下示例中 App 配置的回调 URL 为 `http://www.example.com/callbackCommand?contenttype=json`。

```plaintext
http://www.example.com/callbackBeforePushCommand?contenttype=json
http://www.example.com/callbackBeforeOnlinePushCommand?contenttype=json
```

### 请求参数说明

| 参数 | 说明 |
|-----------------|-----------------------------------------------|
| http | 请求协议为 HTTP，请求方式为 POST |
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
| CallbackCommand | 此处为：callbackBeforePushCommand |
| contenttype | 固定值为：JSON |
| 参数 | 说明 |
| --------------- | ------------------------------------------------- |
| http | 请求协议为 HTTP，请求方式为 POST |
| www.example.com | configy.yaml 中的 callback.url 字段，域名或主机名 |
| CallbackCommand | 此处为：callbackBeforeOnlinePushCommand |
| contenttype | 固定值为：JSON |

### Header
| header名 | 示例值 | 选填 | 类型 | 说明 |
|:------------|:--------------|:----|--------|---------------------|
| operationID | 1646445464564 | 必填 | string | operationID用于全局链路追踪 |

| header 名 | 示例值 | 选填 | 类型 | 说明 |
| :---------- | :------------ | :--- | ------ | ---------------------------- |
| operationID | 1646445464564 | 必填 | string | operationID 用于全局链路追踪 |

### 请求包示例

```json
{
"callbackCommand": "callbackBeforePushCommand",
"callbackCommand": "callbackBeforeOnlinePushCommand",
"platformID": 1,
"platform": "iOS",
"userIDList": ["user123", "user456"],
Expand All @@ -68,59 +76,59 @@ http://www.example.com/callbackBeforePushCommand?contenttype=json

### 请求包字段说明

| 字段 | 类型 | 描述 |
|--------------|----------|--------------------------------------------------|
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
| platformID | int | 平台ID（如 1 代表 iOS，2 代表 Android） |
| platform | string | 平台名称（如 iOS、Android） |
| userIDList | array | 用户ID列表，表示哪些用户将接收此消息 |
| title | string | 推送消息的标题 |
| desc | string | 推送消息的描述或正文内容 |
| ex | string | 额外的推送信息 |
| iOSPushSound | string | iOS 设备上推送消息时使用的声音 |
| iOSBadgeCount | boolean | 是否在iOS应用图标上显示未读消息数 |
| signalInfo | string | 附加信号数据，用于传递额外信息 |
| clientMsgID | string | 客户端消息ID |
| sendID | string | 发送者ID |
| groupID | string | 群组ID（如果消息是发送到群组的） |
| contentType | int | 消息内容类型的ID |
| sessionType | int | 会话类型的ID |
| atUserIDList | array | 被@用户的ID列表 |
| content | string | 发送的消息内容 |

| 字段 | 类型 | 描述 |
| --------------- | ------- | ---------------------------------------- |
| callbackCommand | string | 回调命令，这里是消息推送前的回调 |
| platformID | int | 平台 ID（如 1 代表 iOS，2 代表 Android） |
| platform | string | 平台名称（如 iOS、Android） |
| userIDList | array | 用户 ID 列表，表示哪些用户将接收此消息 |
| title | string | 推送消息的标题 |
| desc | string | 推送消息的描述或正文内容 |
| ex | string | 额外的推送信息 |
| iOSPushSound | string | iOS 设备上推送消息时使用的声音 |
| iOSBadgeCount | boolean | 是否在 iOS 应用图标上显示未读消息数 |
| signalInfo | string | 附加信号数据，用于传递额外信息 |
| 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": "Success",
"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,
"errCode": 0,
"errMsg": "Success",
"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 | 离线推送信息对象。 |
| 字段 | 类型 | 描述 |
| --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| 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 | 离线推送信息对象。 |
Loading