Skip to content

Commit

Permalink
Merge pull request #529 from haoxiuwen/doc-v2
Browse files Browse the repository at this point in the history 
Add REST API of Settinng Remarks of a Contact
  • Loading branch information
@haoxiuwen
haoxiuwen authored Dec 5, 2023
2 parents 43e8a2e + 67347eb commit 9ef86a9
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 0 deletions.
2 changes: 2 additions & 0 deletions docs/document/server-side/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@
| 名称<div style="width: 150px;"></div> | 方法 | 请求 | 描述 |
| :--------------- | :--- | :------------------------------------------ | :----------------------------------------------------------- |
| 发送消息 | POST | 三种请求场景如下：<br/> - 单聊：/{org_name}/{app_name}/messages/users <br/> - 群聊：/{org_name}/{app_name}/messages/chatgroups <br/> - 聊天室：/{org_name}/{app_name}/messages/chatrooms | 聊天相关 API，一般是模拟系统管理员给用户、群组或聊天室发送消息，支持发送文本消息、图片消息、语音消息、视频消息，透传消息，扩展消息以及文件类型消息。 |
| 发送聊天室广播消息 | POST | /{org_name}/{app_name}/messages/chatrooms/broadcast | 向 app 下的所有活跃聊天室（聊天室至少存在一个成员，而且曾经至少发送过一条消息）发送广播消息。 |
| 上传文件 | POST | /{org_name}/{app_name}/chatfiles | 上传语音和图片等文件。 |
| 下载文件 | GET | /{org_name}/{app_name}/chatfiles/{file_uuid} | 下载语音和图片等文件。 |
| 获取聊天记录文件 | GET | /{org_name}/{app_name}/chatmessages/${time} | 获取聊天记录文件。 |
Expand All @@ -133,6 +134,7 @@
| :----------- | :----- | :----------------------------------------------------------- | :--------------------- |
| 添加好友 | POST | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | 添加为好友。 |
| 移除好友 | DELETE | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | 移除好友列表中的用户。 |
| 设置好友备注 | PUT | /{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username} | 设置好有备注。 |
| 获取好友列表 | GET | /{org_name}/{app_name}/users/{owner_username}/contacts/users | 获取好友列表。 |
| 获取黑名单列表 | GET | /{org_name}/{app_name}/users/{owner_username}/blocks/users | 获取黑名单。 |
| 添加用户至黑名单 | POST | /{org_name}/{app_name}/users/{owner_username}/blocks/users | 添加用户至黑名单。 |
Expand Down
73 changes: 73 additions & 0 deletions docs/document/server-side/user_relationship.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,79 @@ curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppT
}
```

## 设置好友备注

你可以调用该接口设置你在当前 app 下的好友的备注，即你和要设置备注的好友需在同一个 App Key 下。

对于免费版即时通讯服务，单个 App Key 下的每个用户的好友数量上限为 100，不同服务套餐包的 App Key 的该数量上限不同，详见[套餐包功能详情](/product/pricing.html#套餐包功能详情)。

### HTTP 请求

```http
PUT https://{host}/{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username}
```

#### 路径参数

| 参数 | 类型 | 是否必需 | 描述 |
| :---------------- | :----- | :------- |:-------------|
| `owner_username` | String | 是 | 当前用户的用户 ID。 |
| `friend_username` | String | 是 | 要设置备注的用户 ID。 |

其他参数及描述详见 [公共参数](#公共参数)。

#### 请求 header

| 参数 | 类型 | 是否必需<div style="width: 80px;"></div> | 描述 |
| :-------------- | :----- | :--------------------------------------- | :------------------------ |
| `Content-Type` | String | 是 | 内容类型。请填 `application/json`。 |
| `Accept` | String | 是 | 内容类型。请填 `application/json`。 |
| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |

### HTTP 响应

#### 响应 body

如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段：

| 字段 | 类型 | 描述 |
| :------------------- |:-------|:--------------------------------------|
| `action` | String | 请求方法。 |
| `status` | String | 好友备注是否设置成功，`ok` 表示设置成功。 |
| `timestamp` | Long | HTTP 响应的 UNIX 时间戳，单位为毫秒。 |
| `uri` | Long | 请求 URL。 |

其他字段及描述详见 [公共参数](#公共参数)。

如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html) 了解可能的原因。

### 示例

#### 请求示例

```shell
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X PUT 'https://{host}/{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
"remark": <remark>
}'
```

#### 响应示例

```json
{
"action": "put",
"duration": 22,
"status": "ok",
"timestamp": 1700633088329,
"uri": "https://{host}/{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username}"
}
```

## 获取好友列表

获取指定用户的好友列表。
Expand Down
2 changes: 2 additions & 0 deletions docs/product/limitationapi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
| 发送单聊消息 | POST | /{org_name}/{app_name}/messages/users | 6000 条/分钟/App Key |
| 发送群聊消息 | POST | /{org_name}/{app_name}/messages/chatgroups | 20 条/秒/App Key |
| 发送聊天室消息 | POST | /{org_name}/{app_name}/messages/chatrooms | 100 条/秒/App Key |
| 发送聊天室广播消息 | POST | /{org_name}/{app_name}/messages/chatrooms/broadcast | 每分钟最多可发 10 次，而且每天最多可发 100 次广播消息。 |
| 上传文件 | POST | /{org_name}/{app_name}/chatfiles | 100 次/秒/App Key |
| 下载文件 | GET | /{org_name}/{app_name}/chatfiles/{file_uuid} | 100 次/秒/App Key |
| 获取历史消息（聊天记录）文件 | GET | /{org_name}/{app_name}/chatmessages/${time} | 10 次/分钟/App Key |
Expand All @@ -81,6 +82,7 @@
| :------------- | :----- | :---------------- | :-------------- |
| 添加好友 | POST | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | 100 次/秒/App Key |
| 移除好友 | DELETE | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | 100 次/秒/App Key |
| 设置好友备注 | PUT | /{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username} | 100 次/秒/App Key |
| 获取好友列表 | GET | /{org_name}/{app_name}/users/{owner_username}/contacts/users | 100 次/秒/App Key |
| 获取黑名单列表 | GET | /{org_name}/{app_name}/users/{owner_username}/blocks/users | 50 次/秒/App Key |
| 添加用户至黑名单 | POST | /{org_name}/{app_name}/users/{owner_username}/blocks/users | 50 次/秒/App Key |
Expand Down

0 comments on commit 9ef86a9

Please sign in to comment.