swagger: '2.0' info: version: 1.0.0 title: beary-openapi description: BearyChat OpenAPI 列表 host: api.bearychat.com basePath: /v1 schemes: - https consumes: - application/json produces: - application/json securityDefinitions: TokenAuth: type: apiKey in: query name: token security: - TokenAuth: [] paths: /meta: get: tags: - meta description: | 返回 BearyChat API 的状态。 responses: '200': description: meta response schema: $ref: '#/definitions/Meta' examples: API 状态: | { "version": "1" } default: description: unexpected error schema: $ref: '#/definitions/Error' /team.info: get: tags: - team description: | 返回当前团队信息。 responses: '200': description: request success schema: $ref: '#/definitions/Team' examples: team response: | { "id": "=bw52O", "subdomain": "openapi", "name": "BearyChat OpenAPI", "email_domain": null, "logo_url": null, "description": "", "plan": "basic", "created": "2017-01-11T12:28:31.000+0000" } default: description: unexpected error schema: $ref: '#/definitions/Error' /user.info: get: tags: - user description: | 返回团队内指定用户完整信息。 responses: '200': description: request success schema: $ref: '#/definitions/User' examples: user response: | { "inactive": false, "role": "normal", "email": "support@bearyinnovative.com", "name": "BearyBot", "type": "assistant", "created": "2017-01-11T12:28:31.000+0000", "id": "=bwMkR", "avatars": { "small": null, "medium": null, "large": null }, "team_id": "=bw52O", "full_name": "倍洽小助手", "mobile": null, "profile": { "bio": null, "position": null, "skype": null } } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - name: user_id in: query description: 指定用户 id，如 \"=bw52O\" required: true type: string /user.list: get: tags: - user description: | 返回团队内的用户列表，获取某个用户的完整信息，请使用 `user.info`. responses: '200': description: request success schema: type: array items: $ref: '#/definitions/User' examples: users response: | [ { "inactive": false, "role": "normal", "email": "support@bearyinnovative.com", "name": "BearyBot", "type": "assistant", "created": "2017-01-11T12:28:31.000+0000", "id": "=bwMkR", "avatars": { "small": null, "medium": null, "large": null }, "team_id": "=bw52O", "full_name": "倍洽小助手", "mobile": null, "profile": { "bio": null, "position": null, "skype": null } } ] default: description: request fail schema: $ref: '#/definitions/Error' /user.me: get: tags: - user description: | 返回当前用户的信息。 responses: '200': description: request success schema: $ref: '#/definitions/User' examples: user response: | { "inactive": false, "role": "normal", "email": "support@bearyinnovative.com", "name": "BearyBot", "type": "assistant", "created": "2017-01-11T12:28:31.000+0000", "id": "=bwMkR", "avatars": { "small": null, "medium": null, "large": null }, "team_id": "=bw52O", "full_name": "倍洽小助手", "mobile": null, "profile": { "bio": null, "position": null, "skype": null } } default: description: request fail schema: $ref: '#/definitions/Error' /user.update_me: patch: tags: - user description: | 更新当前用户信息。 parameters: - in: body name: user_info required: false schema: type: object properties: name: type: string example: beary_bot description: 用户名 (@name) full_name: type: string example: bearybot description: 用户全名 responses: '200': description: request success schema: $ref: '#/definitions/User' examples: user response: | { "inactive": false, "role": "normal", "email": "support@bearyinnovative.com", "name": "BearyBot", "type": "assistant", "created": "2017-01-11T12:28:31.000+0000", "id": "=bwMkR", "avatars": { "small": null, "medium": null, "large": null }, "team_id": "=bw52O", "full_name": "倍洽小助手", "mobile": null, "profile": { "bio": null, "position": null, "skype": null } } default: description: request fail schema: $ref: '#/definitions/Error' consumes: - application/json /vchannel.info: get: tags: - vchannel description: | 返回指定聊天会话的完整信息。 responses: '200': description: request success schema: type: object description: | Channel / SessionChannel / P2PChannel 的其中一种 examples: vchannel response: | // Channel { "private": false, "general": true, "latest_ts": 1486367046281, "uid": "=bw52O", "name": "所有人", "is_member": false, "is_active": true, "type": "normal", "topic": null, "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } // SessionChannel { "latest_ts": "1489242467694", "name": "临时讨论组名称", "is_member": true, "is_active": true, "type": "session", "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } // P2PChannel { "id": "=bw52O", "team_id": "=bw52O", "vchannel_id": "=bw52O", "type": "p2p", "is_active": true, "is_member": true, "member_uids": [ "=bw52O", "=bw52P" ], "latest_ts": 1485238998284 } parameters: - name: vchannel_id in: query description: 聊天会话 id required: true type: string /channel.info: get: tags: - channel description: | 返回指定讨论组的完整信息。 responses: '200': description: request success schema: $ref: '#/definitions/Channel' examples: channel response: | { "private": false, "general": true, "latest_ts": 1486367046281, "uid": "=bw52O", "name": "所有人", "is_member": false, "is_active": true, "type": "normal", "topic": null, "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/TBD' parameters: - name: channel_id in: query description: 讨论组 id， 例如 \"=bw52O\" required: true type: string /channel.list: get: tags: - channel description: | 返回团队内的讨论组列表，获取某个讨论组的完整信息，请使用 `channel.info`. responses: '200': description: request success schema: type: array items: $ref: '#/definitions/Channel' examples: channels response: | [ { "private": false, "general": true, "latest_ts": 1486367046281, "uid": "=bw52O", "name": "所有人", "is_member": false, "is_active": true, "type": "normal", "topic": null, "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } ] default: description: request fail schema: $ref: '#/definitions/Error' /channel.create: post: tags: - channel description: | 创建一个讨论组 responses: '201': description: request success schema: $ref: '#/definitions/Channel' examples: channel response: | { "private": false, "general": true, "latest_ts": 1486367046281, "uid": "=bw52O", "name": "所有人", "is_member": false, "is_active": true, "type": "normal", "topic": null, "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' consumes: - application/json parameters: - in: body name: vchannel_info required: true schema: type: object properties: name: type: string example: 吃喝玩乐在深圳 description: >- 讨论组名称，可以包含 2 到 20 个英文字符或 1 到 10 个中文字符。允许使用数字、下划线 (`_`)、中线 (`-`) 和点。 topic: type: string example: 今天吃什么 description: 讨论组话题 private: type: boolean description: 讨论组是否为私密？ default: false required: - name /channel.archive: post: tags: - channel description: | 归档一个讨论组。 responses: '200': description: request success schema: $ref: '#/definitions/Channel' examples: channel response: | { "private": false, "general": true, "latest_ts": 1486367046281, "uid": "=bw52O", "name": "所有人", "is_member": false, "is_active": false, "type": "normal", "topic": null, "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: channel_id: type: string example: =bw52O description: 讨论组 id required: - channel_id /channel.unarchive: post: tags: - channel description: | 恢复一个已被归档的讨论组。 responses: '200': description: request success schema: $ref: '#/definitions/Channel' examples: channel response: | { "private": false, "general": true, "latest_ts": 1486367046281, "uid": "=bw52O", "name": "所有人", "is_member": false, "is_active": true, "type": "normal", "topic": null, "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: channel_id: type: string example: =bw52O description: 讨论组 id required: - channel_id /channel.leave: post: tags: - channel description: | 当前用户离开讨论组。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: channel_id: type: string example: =bw52O description: 讨论组 id required: - channel_id /channel.join: post: tags: - channel description: | 当前用户加入指定讨论组。 responses: '200': description: request success schema: $ref: '#/definitions/Channel' examples: channel response: | { "private": false, "general": false, "latest_ts": 1486367046281, "uid": "=bw52O", "name": "吃喝玩乐在深圳", "is_member": false, "is_active": true, "type": "normal", "topic": null, "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: channel_id: type: string example: =bw52O description: 讨论组 id required: - channel_id /channel.invite: post: tags: - channel description: | 当前用户邀请一个团队成员加入讨论组。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: channel_id: type: string example: =bw52O description: 讨论组 id invite_uid: type: string example: =bw52O description: 邀请用户 id required: - channel_id - invite_uid /channel.kick: post: tags: - channel description: | 当前用户移除一个讨论组成员。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: channel_id: type: string example: =bw52O description: 讨论组 id kick_uid: type: string example: =bw52O description: 移除用户 id required: - channel_id - kick_uid /channel.kickout: post: tags: - channel description: | 当前用户移除一个讨论组成员。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: channel_id: type: string example: =bw52O description: 讨论组 id kick_uid: type: string example: =bw52O description: 移除用户 id required: - channel_id - kick_uid /session_channel.info: get: tags: - session channel description: | 返回一个临时讨论组的完整信息。 responses: '200': description: request success schema: $ref: '#/definitions/SessionChannel' examples: session channel response: | { "latest_ts": "1489242467694", "name": "临时讨论组名称", "is_member": true, "is_active": true, "type": "session", "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - name: session_channel_id in: query description: 讨论组 id， 例如 \"=bw52O\" required: true type: string /session_channel.list: get: tags: - session channel description: | 返回团队内已经加入的临时讨论组列表，获取某个临时讨论组的完整信息， 请使用 `session_channel.info`. responses: '200': description: request success schema: type: array items: $ref: '#/definitions/SessionChannel' examples: session channels response: | [ { "latest_ts": "1489242467694", "name": "临时讨论组名称", "is_member": true, "is_active": true, "type": "session", "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } ] default: description: request fail schema: $ref: '#/definitions/Error' /session_channel.create: post: tags: - session channel description: | 创建一个临时讨论组。 responses: '201': description: request success schema: $ref: '#/definitions/SessionChannel' examples: session channel responses: | { "latest_ts": "1489242467694", "name": "临时讨论组名称", "is_member": true, "is_active": true, "type": "session", "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: session_channel_info required: true schema: type: object properties: name: type: string example: 吃喝玩乐在深圳 description: >- 讨论组名称，可以包含 2 到 20 个英文字符或 1 到 10 个中文字符。允许使用数字、下划线 (`_`)、中线 (`-`) 和点。 member_uids: type: array example: '["=bw52O", "=bw52P"]' description: 临时讨论组成员 id 列表 items: $ref: '#/definitions/ResponseObjectId' required: - member_uids /session_channel.archive: post: tags: - session channel description: | 归档一个临时讨论组。 responses: '200': description: request success schema: $ref: '#/definitions/SessionChannel' examples: session channel response: | { "latest_ts": "1489242467694", "name": "临时讨论组名称", "is_member": true, "is_active": false, "type": "session", "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: session_channel_id: type: string example: =bw52O description: 临时讨论组 id required: - session_channel_id /session_channel.convert_to_channel: post: tags: - session channel description: | 将临时讨论组转换为讨论组。 responses: '201': description: request success schema: $ref: '#/definitions/Channel' examples: session channel response: | { "latest_ts": "1489242467694", "name": "临时讨论组名称", "is_member": true, "is_active": false, "type": "session", "member_uids": [ "=bw52O" ], "vchannel_id": "=bw52O", "id": "=bw52O", "team_id": "=bw52O" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: channel_info required: true schema: type: object properties: session_channel_id: type: string example: =bw52O description: 临时讨论组 id name: type: string example: 吃喝玩乐在深圳 description: >- 讨论组名称，可以包含 2 到 20 个英文字符或 1 到 10 个中文字符。允许使用数字、下划线 (`_`)、中线 (`-`) 和点。 private: type: boolean default: true description: 讨论组是否为私密? required: - session_channel_id - name /session_channel.leave: post: tags: - session channel description: | 离开临时讨论组。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: session_channel_info required: true schema: type: object properties: session_channel_id: type: string example: =bw52O description: 临时讨论组 id required: - session_channel_id /session_channel.invite: post: tags: - session channel description: | 邀请一个团队成员加入临时讨论组。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: session_channel_info required: true schema: type: object properties: session_channel_id: type: string example: =bw52O description: 临时讨论组 id invite_uid: type: string example: =bw52O description: 邀请用户 id required: - session_channel_id - invite_uid /session_channel.kick: post: tags: - session channel description: | 移除一个临时讨论组成员。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: session_channel_info required: true schema: type: object properties: session_channel_id: type: string example: =bw52O description: 临时讨论组 id kick_uid: type: string example: =bw52O description: 移除用户 id required: - session_channel_id - kick_uid /session_channel.kickout: post: tags: - session channel description: | 移除一个临时讨论组成员。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: session_channel_info required: true schema: type: object properties: session_channel_id: type: string example: =bw52O description: 临时讨论组 id kick_uid: type: string example: =bw52O description: 移除用户 id required: - session_channel_id - kick_uid /p2p.info: get: tags: - p2p description: | 返回一个 P2P 聊天会话的完整信息。 responses: '200': description: request success schema: $ref: '#/definitions/P2PChannel' examples: p2p response: | { "id": "=bw52O", "team_id": "=bw52O", "vchannel_id": "=bw52O", "type": "p2p", "is_active": true, "is_member": true, "member_uids": [ "=bw52O", "=bw52P" ], "latest_ts": 1485238998284 } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - name: p2p_channel_id in: query description: P2P 聊天会话 id， 例如\"=bw52O\" required: true type: string /p2p.list: get: tags: - p2p description: | 返回 P2P 聊天会话列表，获取某个 P2P 会话的完整信息，请使用 `p2p.info`. responses: '200': description: request success schema: type: array items: $ref: '#/definitions/P2PChannel' examples: p2p list response: | [ { "id": "=bw52O", "team_id": "=bw52O", "vchannel_id": "=bw52O", "type": "p2p", "is_active": true, "is_member": true, "member_uids": [ "=bw52O", "=bw52P" ], "latest_ts": 1485238998284 } ] default: description: request fail schema: $ref: '#/definitions/Error' /p2p.create: post: tags: - p2p description: | 创建一个 P2P 聊天会话。 responses: '201': description: request success schema: $ref: '#/definitions/P2PChannel' examples: p2p response: | { "id": "=bw52O", "team_id": "=bw52O", "vchannel_id": "=bw52O", "type": "p2p", "is_active": true, "is_member": true, "member_uids": [ "=bw52O", "=bw52P" ], "latest_ts": 1485238998284 } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: p2p_info required: true schema: type: object properties: user_id: type: string example: =bw52O description: P2P 聊天另外一方的用户 id required: - user_id /message.query: post: tags: - message description: | 查询指定 vchannel 下的消息列表。支持以下几种查询算法： ### `latest` 查询 vchannel 下最新的消息，支持参数： - `limit`: 查询数量限制，最大值为 100, 默认 20 ### `since` 从指定位置开始拉取若干条消息，支持参数： - `key`: 开始位置的消息 key, 不可以和 `ts` 同时使用 - `ts`: 开始位置的消息 ts, 不可以和 `ts` 同时使用 - `forward`: 向前（时间发生方向）获取条数 - `backward`: 向后（时间发生方向）获取条数 **注意**: 1. 使用 `key` 查询时，查询区间不包括 key 对应的消息 2. 使用 `ts` 查询时，查询区间包括 ts 对应的消息 3. `forward` / `backward` 参数可以同时使用 4. `forward` / `backward` 参数最大值为 100, 5. `forward` / `backward` 均未指定时，默认使用 `forward=100` ### `window` 拉取一定时间窗口内的消息，支持参数： - `from_key` / `to_key`: 窗口区间的消息 key - `from_ts` / `to_ts`: 窗口区间的消息 ts - `forward`: 从 from 方向往 to 方向取的消息数 - `backward`: 从 to 方向往 from 方向取的消息数 **注意**: 1. `{from,to}_key` 和 `{from,to}_ts` 不可以混用 2. 使用 `{from,to}_key` 查询时，查询区间不包括 key 对应的消息 3. 使用 `{from,to}_ts` 查询时，查询区间包括 ts 对应的消息 4. `forward` 和 `backward` 参数只能选其中一个 5. `forward` / `backward` 均未指定时，默认使用 `forward=100` 6. 如果查询区间开始值比结束值大，返回空结果 responses: '200': description: request success schema: $ref: '#/definitions/MessageQueryResult' examples: message query response: | { "messages": [ { "key": "1485236262366.0193", "updated": "2017-01-24T13:37:42.000+0000", "is_channel": false, "uid": "=bw52O", "fallback": null, "attachments": [], "created": "2017-01-24T13:37:42.000+0000", "vchannel_id": "=bw52O", "refer_key": null, "robot_id": null, "created_ts": 1485236262366, "team_id": "=bw52O", "subtype": "normal", "text": "hello" } ] } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: message_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 待查询 vchannel_id query: $ref: '#/definitions/MessageQuery' required: - vchannel_id - query /message.info: get: tags: - message description: | 返回一条消息的信息。 responses: '200': description: request success schema: $ref: '#/definitions/Message' examples: message response: | { "key": "1485236262366.0193", "updated": "2017-01-24T13:37:42.000+0000", "is_channel": false, "uid": "=bw52O", "fallback": null, "attachments": [], "created": "2017-01-24T13:37:42.000+0000", "vchannel_id": "=bw52O", "refer_key": null, "robot_id": null, "created_ts": 1485236262366, "team_id": "=bw52O", "subtype": "normal", "text": "hello" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - name: vchannel_id type: string in: query description: 指定的目标聊天会话 id，例如 \"=bw52O\" required: true - name: message_key type: string in: query description: 获取消息的 key，例如 \"1487667236785.0077\" required: true /message.create: post: tags: - message description: | 发送一条消息到指定聊天会话。 responses: '201': description: request success schema: $ref: '#/definitions/Message' examples: message response: | { "key": "1485236262366.0193", "updated": "2017-01-24T13:37:42.000+0000", "is_channel": false, "uid": "=bw52O", "fallback": null, "attachments": [], "created": "2017-01-24T13:37:42.000+0000", "vchannel_id": "=bw52O", "refer_key": null, "robot_id": null, "created_ts": 1485236262366, "team_id": "=bw52O", "subtype": "normal", "text": "hello" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: message_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 指定的目标聊天会话 id text: type: string example: 中午吃啥啊？ description: 消息内容 attachments: type: array example: 中午吃啥啊？ description: 消息附件 items: $ref: '#/definitions/MessageAttachment' required: - vchannel_id - text /message.delete: post: tags: - message description: | 删除一条消息。 responses: '204': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: message_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 待查询 vchannel_id message_key: type: string description: 删除的消息 key example: '1487667236785.0077' required: - vchannel_id - message_key /message.update_text: patch: tags: - message description: | 更新一条消息的内容。 responses: '200': description: request success schema: $ref: '#/definitions/Message' examples: message response: | { "key": "1485236262366.0193", "updated": "2017-01-24T13:37:42.000+0000", "is_channel": false, "uid": "=bw52O", "fallback": null, "attachments": [], "created": "2017-01-24T13:37:42.000+0000", "vchannel_id": "=bw52O", "refer_key": null, "robot_id": null, "created_ts": 1485236262366, "team_id": "=bw52O", "subtype": "normal", "text": "hello" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: message_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 待查询 vchannel_id message_key: type: string description: 更新的消息 key example: '1487667236785.0077' text: type: string description: 更新的消息内容 example: 中午吃啥啊？ required: - vchannel_id - message_key - text /message.forward: post: tags: - message description: | 转发消息 responses: '200': description: request success schema: $ref: '#/definitions/MessageForward' examples: message response: | { "repost": { "uid": "=bw52T", "vchannel_id": "=bw52O", "robot_id": null, "created_ts": 1539056624039, "message_key": "1539056624039.0143", "id": "=bw52Q", "team_id": "=bw52U", "subtype": "normal", "text": "当测不测，反受其乱" }, "key": "1539079267590.0001", "updated": "2018-10-09T10:01:08.000+0000", "is_channel": true, "uid": "=bw52W", "thread_key": null, "created": "2018-10-09T10:01:08.000+0000", "vchannel_id": "=bw52O", "refer_key": null, "robot_id": null, "edited": false, "created_ts": 1539079267590, "pin_id": null, "id": "=bw52Z", "team_id": "=bw52U", "text_i18n": { "zh-CN": "转发了消息", "en": "fowarded message" }, "reactions": [], "subtype": "forwarded", "text": "转发了消息" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: message_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 转发的消息所在的位置 id key: type: string description: 更新的消息 key example: '1487667236785.0077' to_vchannel_id: type: string example: =bw52O description: 转发目的会话 id required: - vchannel_id - key - to_vchannel_id /message_pin.list: get: tags: - message_pin description: | 查询某个聊天会话的置顶消息列表 responses: '200': description: request success schema: type: array items: $ref: '#/definitions/MessagePin' examples: message-pin response: | [ { "id": "=bw52T", "team_id": "=bw52U", "uid": "=bw52W", "vchannel_id": "=bw52O", "message_id": "=bw53a", "message_key": "1539079277448.0002", "created_at": "2018-10-10T09:48:55.000+0800", "updated_at": "2018-10-10T09:48:55.000+0800", "message": null } ] default: description: request fail schema: $ref: '#/definitions/Error' parameters: - name: vchannel_id in: query description: 讨论组 id， 例如 \"=bw52O\" required: true type: string /message_pin.create: post: tags: - message_pin description: | 置顶消息 responses: '200': description: request success schema: $ref: '#/definitions/MessagePin' examples: message_pin response: | { "id": "=bw52T", "team_id": "=bw52U", "uid": "=bw52W", "vchannel_id": "=bw52O", "message_id": "=bw53a", "message_key": "1539079277448.0002", "created_at": "2018-10-10T09:48:55.000+0800", "updated_at": "2018-10-10T09:48:55.000+0800" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: message_pin_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 消息所在的频道 message_key: type: string description: 想要置顶的消息 key example: '1487667236785.0077' required: - vchannel_id - message_key /message_pin.delete: post: tags: - message_pin description: | 删除置顶消息 responses: '200': description: request success schema: $ref: '#/definitions/NoContent' default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: message_pin_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 消息所在的频道 pin_id: type: string description: 置顶消息的 id example: =bw52O required: - vchannel_id - pin_id /reaction.create: post: tags: - reaction description: | 创建消息 Reaction responses: '200': description: request success schema: $ref: '#/definitions/MessageReaction' examples: reaction created response: | { "id": "=bw52Q", "team_id": "=bw52R", "uid": "=bw52S", "message_id": "=bw52Q", "message_key": "1540460114044.0100", "reaction": ":smile:" "created_ts": 1540461431018, "created": "2018-10-25T09:57:11.000+0000", "updated": "2018-10-25T09:57:11.000+0000" } default: description: request fail schema: $ref: '#/definitions/Error' parameters: - in: body name: reaction_create_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 消息所在的频道 key: type: string description: 想要加 sticker 的 message 的 key example: '1540460114044.0100' reaction: type: string description: 想要添加的 reaction 名 example: ':smile:' required: - vchannel_id - key - reaction /reaction.delete: post: tags: - reaction description: | 删除消息 reaction responses: '200': description: request success schema: $ref: '#/definitions/NoContent' default: description: unexpected error schema: $ref: '#/definitions/Error' parameters: - in: body name: reaction_delete_info required: true schema: type: object properties: vchannel_id: type: string example: =bw52O description: 消息所在的频道 key: type: string description: 想要删 sticker 的 message 的 key example: '1540460114044.0100' reaction: type: string description: 想要删除的 reaction 名 example: ':smile:' required: - vchannel_id - key - reaction /emoji.list: get: tags: - emoji & sticker description: | 返回团队内的自定义 emoji 列表 responses: '200': description: request success schema: type: array items: $ref: '#/definitions/Emoji' examples: emojis response: | [ { "id": "=bw52O", "uid": "=bw52O", "team_id": "=bw52O", "name": "hello", "type": "emoji", "created": "2017-03-13T13:54:16.000+0000", "updated": "2017-03-13T13:54:16.000+0000", "url": "http://example.com/1.jpg" } ] default: description: unexpected error schema: $ref: '#/definitions/Error' /sticker.list: get: tags: - emoji & sticker description: | 返回当前用户的自定义 sticker 列表 responses: '200': description: request success schema: type: array items: $ref: '#/definitions/StickerPack' examples: sticker packs response: | [ { "pack": "黑白熊静态", "stickers": [ { "url": "https://dn-bearychat.qbox.me/sticker-gif-20.gif", "name": "累", "width": 240, "height": 240 } ] } ] default: description: unexpected error schema: $ref: '#/definitions/Error' /rtm.start: post: tags: - rtm description: | 打开 RTM 连接会话 responses: '200': description: request success schema: $ref: '#/definitions/RTMStart' examples: rtm response: | { "ws_host": "wss://rtm.bearychat.com/nimbus/ws:xxx", "user": { "inactive": false, "role": "normal", "email": "support@bearyinnovative.com", "name": "BearyBot", "type": "assistant", "created": "2017-01-11T12:28:31.000+0000", "id": "=bwMkR", "avatars": { "small": null, "medium": null, "large": null }, "team_id": "=bw52O", "full_name": "倍洽小助手", "mobile": null, "profile": { "bio": null, "position": null, "skype": null } } } default: description: request fail schema: $ref: '#/definitions/Error' definitions: VChannelId: description: 聊天会话 id type: string VChannelType: description: 聊天会话类型 type: string enum: - normal - session - p2p Meta: required: - version properties: version: description: 当前 api 版本 type: string Team: required: - id - subdomain - name - email_domain - logo_url - description - plan - created properties: id: $ref: '#/definitions/ResponseObjectId' subdomain: description: 团队 subdomain type: string name: description: 团队名称 type: string email_domain: description: 团队邮箱域名 type: string logo_url: description: 团队头像地址 type: string description: description: 团队简介 type: string plan: $ref: '#/definitions/TeamPlan' created: description: 团队创建时间 type: string format: data-time TeamPlan: type: string enum: - basic - standard User: required: - id - team_id - email - mobile - name - full_name - type - role - avatars - profile - inactive - created properties: id: $ref: '#/definitions/ResponseObjectId' team_id: $ref: '#/definitions/ResponseObjectId' email: description: 用户注册邮箱地址 type: string format: email mobile: description: 用户注册手机号码 type: string name: description: 用户名 type: string full_name: description: 用户全名 type: string type: description: 用户类型 type: string enum: - normal - assistant - hubot role: description: 用户在团队内的身份 type: string enum: - owner - admin - normal - visitor avatars: $ref: '#/definitions/UserAvatar' profile: $ref: '#/definitions/UserProfile' inactive: description: 用户是否已注销 type: boolean created: description: 用户加入时间 type: string format: data-time UserAvatar: required: - small - medium - large properties: small: type: string medium: type: string large: type: string UserProfile: properties: bio: description: 用户个人简介 type: string position: description: 用户个人资料 type: string skype: description: 用户 skype type: string Channel: required: - id - team_id - uid - vchannel_id - name - topic - type - general - private - is_active - is_member - member_uids - latest_ts properties: id: $ref: '#/definitions/ResponseObjectId' team_id: $ref: '#/definitions/ResponseObjectId' uid: $ref: '#/definitions/ResponseObjectId' vchannel_id: $ref: '#/definitions/VChannelId' name: description: 讨论组名称 type: string topic: description: 讨论组话题 type: string type: $ref: '#/definitions/VChannelType' general: description: 讨论组是否为`所有人`讨论组？ type: boolean private: description: 讨论组是否为私密讨论组？ type: boolean is_active: description: 会话是否有效 type: boolean is_member: description: 当前用户是否为讨论组成员？ type: boolean member_uids: description: 讨论组成员 id 列表 type: array items: $ref: '#/definitions/ResponseObjectId' latest_ts: description: 讨论组最新一条消息的 ts type: integer SessionChannel: required: - id - team_id - vchannel_id - name - type - is_active - is_member - member_uids - latest_ts properties: id: $ref: '#/definitions/ResponseObjectId' team_id: $ref: '#/definitions/ResponseObjectId' vchannel_id: $ref: '#/definitions/VChannelId' name: description: 临时讨论组名称，如果为 null 则表示未设置名称 type: string type: $ref: '#/definitions/VChannelType' is_active: description: 会话是否有效 type: boolean is_member: description: 当前用户是否为临时讨论组成员？ type: boolean member_uids: description: 临时讨论组成员 id 列表 type: array items: $ref: '#/definitions/ResponseObjectId' latest_ts: description: 临时讨论组最新一条消息的 ts type: integer P2PChannel: required: - id - team_id - vchannel_id - type - is_active - is_member - member_uids - latest_ts properties: id: $ref: '#/definitions/ResponseObjectId' team_id: $ref: '#/definitions/ResponseObjectId' vchannel_id: $ref: '#/definitions/VChannelId' type: $ref: '#/definitions/VChannelType' is_active: description: 会话是否有效 type: boolean is_member: description: 当前用户是否为对话成员？ type: boolean member_uids: description: P2P 对话成员 id 列表 type: array items: $ref: '#/definitions/ResponseObjectId' latest_ts: description: P2P 对话最新一条消息的 ts type: integer MessageKey: description: 消息唯一索引 key type: string MessageSubtype: description: 消息类型 type: string enum: - normal - info MessageAttachment: description: 消息附件 (TBD) type: string Message: required: - key - team_id - uid - robot_id - vchannel_id - refer_key - subtype - text - fallback - attachments - created - created_ts - updated - is_channel properties: key: $ref: '#/definitions/MessageKey' team_id: $ref: '#/definitions/ResponseObjectId' uid: $ref: '#/definitions/ResponseObjectId' robot_id: $ref: '#/definitions/ResponseObjectId' vchannel_id: $ref: '#/definitions/VChannelId' refer_key: $ref: '#/definitions/MessageKey' subtype: $ref: '#/definitions/MessageSubtype' text: description: 消息正文 type: string fallback: description: 消息提醒使用正文 type: string attachments: description: 消息附件 type: array items: $ref: '#/definitions/MessageAttachment' created: description: 消息创建时间 type: string format: date-time created_ts: description: 消息创建时间戳 type: integer format: int32 updated: description: 消息最后修改时间 type: string format: date-time is_channel: description: 消息是否为讨论组消息？ type: boolean MessagePin: description: 置顶消息 properties: id: $ref: '#/definitions/ResponseObjectId' team_id: $ref: '#/definitions/ResponseObjectId' uid: $ref: '#/definitions/ResponseObjectId' vchannel_id: $ref: '#/definitions/ResponseObjectId' message_id: $ref: '#/definitions/ResponseObjectId' message_key: $ref: '#/definitions/MessageKey' created_at: description: 创建时间 type: string format: data-time updated_at: description: 更新时间 type: string format: data-time message: description: 消息 type: string MessageReaction: description: | 消息 Reaction properties: id: $ref: '#/definitions/ResponseObjectId' uid: $ref: '#/definitions/ResponseObjectId' team_id: $ref: '#/definitions/ResponseObjectId' message_id: $ref: '#/definitions/ResponseObjectId' message_key: $ref: '#/definitions/MessageKey' reaction: description: reaction 名 type: string created_ts: description: 消息创建时间戳 type: integer format: int32 created: description: 创建时间 type: string format: data-time updated: description: 更新时间 type: string format: data-time MessageQueryWindow: description: | 拉取一定时间窗口里面的消息 {from,to}_key / {from,to}_ts 不能混用，优先使用 {from,to}_key 对 from_{key,ts} to_{key,ts} 必须成对出现 使用消息 key 查询的时候，查询区间为 (from_key, to_key) 使用消息 ts 查询的时候，查询区间为 [from_ts, to_ts] forward / backward 可选其一 查询结果最多返回 100 条消息： - forward / backward 最大值为 100 - 不指定 forward / backward 时，默认返回 forward=100 的消息记录 - 如果查询区间开始值比结束值大，返回空结果 properties: form_key: description: 区间开始的消息 `key` type: string to_key: description: 区间结束的消息 `key` type: string from_ts: description: 区间开始的消息时间戳 type: integer format: int32 to_ts: description: 区间结束的消息时间戳 type: integer format: int32 forward: description: 向前获取 n 条消息 type: integer format: int32 backward: description: 向后获取 n 条消息 type: integer format: int32 MessageQuerySince: description: | 从指定位置开始拉取若干条消息 key / ts 不能混用，优先使用 key forward / backward 可同时使用，默认为 forward=100 使用消息 key 查询的时候，查询区间为 (key, +inf) / (-inf, key) 使用消息 ts 查询的时候，查询区间为 [ts, +inf) / (-inf, ts] forward / backward 可选其一 查询结果最多返回 100 条消息： - forward / backward 最大值为 100 - 不指定 forward / backward 时，默认返回 forward=100 的消息记录 - 如果同时使用 forward / backward 查询，返回消息保证 总数 <= forward + backward properties: key: description: 指定位置的消息 `key` type: string ts: description: 指定位置的消息时间戳 type: integer format: int32 forward: description: 向前获取 n 条消息 type: integer format: int32 backward: description: 向后获取 n 条消息 type: integer format: int32 MessageQueryLatest: description: | 获取该 vchannel 下的最新消息列表 查询结果最多返回 100 条消息： - limit 最大值为 100 - 不指定 limit 时，limit 默认为 20 properties: limit: description: 获取 n 条消息 type: integer format: int32 MessageQuery: description: | window / since / latest / thread 只能存在其中一种查询方法 如果带有多种查询方法，则只以第一个方法为准 properties: window: $ref: '#/definitions/MessageQueryWindow' since: $ref: '#/definitions/MessageQuerySince' latest: $ref: '#/definitions/MessageQueryLatest' MessageQueryResult: required: - messages properties: messages: description: 查询到的消息列表 type: array items: $ref: '#/definitions/Message' MessageForward: properties: repost: $ref: '#/definitions/Message' key: description: 转发后的消息的 key type: string updated: description: 更新时间 type: string format: data-time is_channel: description: 是否为在群组内发送的消息 type: boolean uid: $ref: '#/definitions/ResponseObjectId' thread_key: description: 线程 key type: string created: description: 创建时间 type: string format: data-time vchannel_id: $ref: '#/definitions/ResponseObjectId' refer_key: description: 转发 key type: string robot_id: $ref: '#/definitions/ResponseObjectId' edited: description: 是否修改过 type: boolean created_ts: description: 消息创建时间戳 type: integer format: int32 RTMStart: required: - user - ws_host properties: user: $ref: '#/definitions/User' ws_host: description: rtm 连接地址 type: string Emoji: required: - id - uid - team_id - name - type - created - updated - url properties: id: description: emoji id type: string uid: description: 创建用户 id type: string team_id: description: 所属团队 id type: string name: description: 名称 type: string type: description: 资源类型 type: string created: description: 创建时间 type: string format: date-time updated: description: 最后修改时间 type: string format: date-time url: description: emoji url Sticker: required: - url - name - width - height properties: url: description: sticker url type: string name: description: 名称 type: string width: description: 图片宽度 type: integer format: int32 height: description: 图片高度 type: integer format: int32 StickerPack: description: 表情包 required: - pack - stickers properties: pack: description: 表情包名称 type: string stickers: description: 包含的表情 type: array items: $ref: '#/definitions/Sticker' Error: required: - code - error properties: code: $ref: '#/definitions/ResponseCode' error: $ref: '#/definitions/ResponseError' NoContent: description: NO CONTENT TBD: description: 待定义 type: string ResponseObjectId: type: string ResponseCode: type: integer format: int32 ResponseError: type: string format: string