swagger: "2.0"
info:
  version: 1.0.0
  title: beary-openapi
  description: BearyChat OpenAPI 列表
host: api.bearychat.com
basePath: /v1
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /meta:
    get:
      description: |
        返回 BearyChat API 的状态。
      authentication: false
      responses:
        200:
          description: meta response
          schema:
            type: object
            properties:
              code:
                $ref: '#/definitions/ResponseCode'
              result:
                $ref: '#/definitions/Meta'
          example: |
            {
              "version": "1"
            }
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  #---------------------------------------------------------------------------
  # 团队相关
  #---------------------------------------------------------------------------

  /team.info:
    get:
      description: |
        返回当前团队信息。
      authentication: true
      responses:
        200:
          description: team response
          schema:
            $ref: '#/definitions/Team'
          example: |
            {
              "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:
      description: |
        返回团队内指定用户完整信息。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/User'
          example: |
            {
              "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:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: user_id
          in: body
          description: 指定用户 id
          example: '=bw52O'
          required: true
          type: string

  /user.list:
    get:
      description: |
        返回团队内的用户列表，获取某个用户的完整信息，请使用 `user.info`.
      authentication: true
      responses:
        200:
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
          example: |
            [
              {
                "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:
          schema:
            $ref: '#/definitions/Error'

  /user.me:
    get:
      description: |
        返回当前用户的信息。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/User'
          example: |
            {
              "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:
          schema:
            $ref: '#/definitions/Error'

  # /user.update_me: TODO

  #---------------------------------------------------------------------------
  # 讨论组相关
  #---------------------------------------------------------------------------

  /channel.info:
    get:
      description: |
        返回指定讨论组的完整信息。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/Channel'
          example: |
            {
              "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:
          schema:
            $ref: '#/definitions/TBD'
      parameters:
        - name: channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string

  /channel.list:
    get:
      description: |
        返回团队内的讨论组列表，获取某个讨论组的完整信息，请使用 `channel.info`.
      authentication: true
      responses:
        200:
          schema:
            type: array
            items:
              $ref: '#/definitions/Channel'
          example: |
            [
              {
                "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:
          schema:
            $ref: '#/definitions/Error'

  /channel.create:
    post:
      description: |
        创建一个讨论组
      authentication: true
      responses:
        201:
          schema:
            $ref: '#/definitions/Channel'
          example: |
            {
              "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"
            }
        # TODO invalid payload response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: name
          in: body
          description: |
            讨论组名称，可以包含 2 到 20 个英文字符或 1 到 10 个中文字符。
            允许使用数字、下划线 (`_`)、中线 (`-`) 和点。
          example: '吃喝玩乐在深圳'
          required: true
          type: string
        - name: topic
          in: body
          description: 讨论组话题
          example: '今天吃什么？'
          required: false
          type: string
        - name: private
          in: body
          description: 讨论组是否为私密？
          required: false
          type: boolean
          default: false

  /channel.archive:
    post:
      description: |
        归档一个讨论组。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/Channel'
          example: |
            {
              "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"
            }
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string

  /channel.unarchive:
    post:
      description: |
        恢复一个已被归档的讨论组。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/Channel'
          example: |
            {
              "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"
            }
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string

  /channel.leave:
    post:
      description: |
        当前用户离开讨论组。
      authentication: true
      responses:
        204:
          schema:
            $ref: '#/definitions/OK'
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string

  /channel.join:
    post:
      description: |
        当前用户加入指定讨论组。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/Channel'
          example: |
            {
              "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"
            }
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string

  /channel.invite:
    post:
      description: |
        当前用户邀请一个团队成员加入讨论组。
      authentication: true
      responses:
        204:
          schema:
            $ref: '#/definitions/OK'
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string
        - name: invite_uid
          in: body
          description: 邀请用户 id
          example: "=bw52O"
          required: true
          type: string

  /channel.kick:
    post:
      description: |
        当前用户移除一个讨论组成员。
      authentication: true
      responses:
        204:
          schema:
            $ref: '#/definitions/OK'
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string
        - name: kick_uid
          in: body
          description: 移除用户 id
          example: "=bw52O"
          required: true
          type: string

  # /channel.update: TODO

  #---------------------------------------------------------------------------
  # 临时讨论组相关
  #---------------------------------------------------------------------------

  /session_channel.info:
    get:
      description: |
        返回一个临时讨论组的完整信息。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/SessionChannel'
          example: |
            {
              "latest_ts": "1489242467694",
              "name": "临时讨论组名称",
              "is_member": true,
              "is_active": true,
              "type": "session",
              "member_uids": [
                "=bw52O"
              ],
              "vchannel_id": "=bw52O",
              "id": "=bw52O",
              "team_id": "=bw52O"
            }
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: session_channel_id
          in: body
          description: 讨论组 id
          example: "=bw52O"
          required: true
          type: string

  /session_channel.list:
    get:
      description: |
        返回团队内已经加入的临时讨论组列表，获取某个临时讨论组的完整信息，
        请使用 `session_channel.info`.
      authentication: true
      responses:
        200:
          schema:
            type: array
            items:
              $ref: '#/definitions/SessionChannel'
          example: |
            [
              {
                "latest_ts": "1489242467694",
                "name": "临时讨论组名称",
                "is_member": true,
                "is_active": true,
                "type": "session",
                "member_uids": [
                  "=bw52O"
                ],
                "vchannel_id": "=bw52O",
                "id": "=bw52O",
                "team_id": "=bw52O"
              }
            ]
        default:
          schema:
            $ref: '#/definitions/Error'

  /session_channel.create:
    post:
      description: |
        创建一个临时讨论组。
      authentication: true
      responses:
        201:
          schema:
            $ref: '#/definitions/SessionChannel'
          example: |
            {
              "latest_ts": "1489242467694",
              "name": "临时讨论组名称",
              "is_member": true,
              "is_active": true,
              "type": "session",
              "member_uids": [
                "=bw52O"
              ],
              "vchannel_id": "=bw52O",
              "id": "=bw52O",
              "team_id": "=bw52O"
            }
        # TODO invalid payload response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: name
          in: body
          description: |
            临时讨论组名称，可以包含 2 到 20 个英文字符或 1 到 10 个中文字符。
            允许使用数字、下划线 (`_`)、中线 (`-`) 和点。
          example: '吃喝玩乐在深圳'
          required: false
          type: string
        - name: member_uids
          in: body
          description: 临时讨论组成员 id 列表
          example: '["=bw52O", "=bw52P"]'
          required: true
          type: array
          items:
            $ref: '#/definitions/ResponseObjectId'

  /session_channel.archive:
    post:
      description: |
        归档一个临时讨论组。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/SessionChannel'
          example: |
            {
              "latest_ts": "1489242467694",
              "name": "临时讨论组名称",
              "is_member": true,
              "is_active": false,
              "type": "session",
              "member_uids": [
                "=bw52O"
              ],
              "vchannel_id": "=bw52O",
              "id": "=bw52O",
              "team_id": "=bw52O"
            }
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: session_channel_id
          in: body
          description: 临时讨论组 id
          example: '=bw52O'
          required: true
          type: string

  /session_channel.convert_to_channel:
    post:
      description: |
        将临时讨论组转换为讨论组。
      authentication: true
      responses:
        201:
          schema:
            $ref: '#/definitions/Channel'
          example: |
            {
              "latest_ts": "1489242467694",
              "name": "临时讨论组名称",
              "is_member": true,
              "is_active": false,
              "type": "session",
              "member_uids": [
                "=bw52O"
              ],
              "vchannel_id": "=bw52O",
              "id": "=bw52O",
              "team_id": "=bw52O"
            }
        # TODO permission denied response
        # TODO invalid payload response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: session_channel_id
          in: body
          description: 临时讨论组 id
          example: '=bw52O'
          required: true
          type: string
        - name: name
          in: body
          description: |
            讨论组名称，可以包含 2 到 20 个英文字符或 1 到 10 个中文字符。
            允许使用数字、下划线 (`_`)、中线 (`-`) 和点。
          example: '吃喝玩乐在深圳'
          required: true
          type: string
        - name: private
          in: body
          description: 讨论组是否为私密？
          required: false
          type: boolean
          default: true

  /session_channel.leave:
    post:
      description: |
        离开临时讨论组。
      authentication: true
      responses:
        204:
          schema:
            $ref: '#/definitions/OK'
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/TBD'
      parameters:
        - name: session_channel_id
          in: body
          description: 临时讨论组 id
          example: '=bw52O'
          required: true
          type: string

  /session_channel.invite:
    post:
      description: |
        邀请一个团队成员加入临时讨论组。
      authentication: true
      responses:
        204:
          schema:
            $ref: '#/definitions/OK'
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: session_channel_id
          in: body
          description: 临时讨论组 id
          example: '=bw52O'
          required: true
          type: string
        - name: invite_uid
          in: body
          description: 邀请用户 id
          example: '=bw52O'
          required: true
          type: string

  /session_channel.kick:
    post:
      description: |
        移除一个临时讨论组成员。
      authentication: true
      responses:
        204:
          schema:
            $ref: '#/definitions/OK'
        # TODO permission denied response
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: session_channel_id
          in: body
          description: 临时讨论组 id
          example: '=bw52O'
          required: true
          type: string
        - name: kick_uid
          in: body
          description: 邀请用户 id
          example: '=bw52O'
          required: true
          type: string

  # /session_channel.update: TODO

  #---------------------------------------------------------------------------
  # P2P 聊天列表相关
  #---------------------------------------------------------------------------

  /p2p.info:
    get:
      description: |
        返回一个 P2P 聊天会话的完整信息。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/P2PChannel'
          example: |
            {
              "id": "=bw52O",
              "team_id": "=bw52O",
              "vchannel_id": "=bw52O",
              "type": "p2p",
              "is_active": true,
              "is_member": true,
              "member_uids": [
                "=bw52O",
                "=bw52P"
              ],
              "latest_ts": 1485238998284
            }
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: p2p_channel_id
          in: body
          description: P2P 聊天会话 id
          example: '=bw52O'
          required: true
          type: string

  /p2p.list:
    get:
      description: |
        返回 P2P 聊天会话列表，获取某个 P2P 会话的完整信息，请使用 `p2p.info`.
      authentication: true
      responses:
        default:
          200:
            schema:
              type: array
              items:
                $ref: '#/definitions/P2PChannel'
          example: |
            [
              {
                "id": "=bw52O",
                "team_id": "=bw52O",
                "vchannel_id": "=bw52O",
                "type": "p2p",
                "is_active": true,
                "is_member": true,
                "member_uids": [
                  "=bw52O",
                  "=bw52P"
                ],
                "latest_ts": 1485238998284
              }
            ]
          schema:
            $ref: '#/definitions/Error'

  /p2p.create:
    post:
      description: |
        创建一个 P2P 聊天会话。
      authentication: true
      responses:
        201:
          schema:
            $ref: '#/definitions/P2PChannel'
          example: |
            {
              "id": "=bw52O",
              "team_id": "=bw52O",
              "vchannel_id": "=bw52O",
              "type": "p2p",
              "is_active": true,
              "is_member": true,
              "member_uids": [
                "=bw52O",
                "=bw52P"
              ],
              "latest_ts": 1485238998284
            }
        # TODO invalid payload error
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: user_id
          in: body
          description: P2P 聊天另外一方的用户 id
          example: '=bw52O'
          required: true
          type: string

  #---------------------------------------------------------------------------
  # 消息相关
  #---------------------------------------------------------------------------

  /message.query:
    post:
      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. 如果查询区间开始值比结束值大，返回空结果

      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/MessageQueryResult'
          example: |
            {
              "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:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: vchannel_id
          in: body
          description: 待查询 vchannel_id
          required: true
          example: '=bw52O'
          type: string
        - name: query
          in: body
          description: 消息查询 payload
          required: true
          $ref: '#/definitions/MessageQuery'
      parameters_example: |
        // latest
        {
          "vchannel_id": "=bw52O",
          "query": {
            "latest": {
              "limit": 10
            }
          }
        }

        // since
        {
          "vchannel_id": "=bw52O",
          "query": {
            "since": {
              "ts": 1485236262366
            }
          }
        }

        // window
        {
          "vchannel_id": "=bw52O",
          "query": {
            "window": {
              "from_ts": 1485236262366,
              "to_ts": 1485236362366,
              "forward": 100
            }
          }
        }

  /message.info:
    get:
      description: |
        返回一条消息的信息。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/Message'
          example: |
            {
              "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:
          schema:
            $ref: '#/definitions/Error'
          key:
      parameters:
        - name: vchannel_id
          in: body
          description: 指定的目标聊天会话 id
          example: '=bw52O'
          required: true
          $ref: '#/definitions/VChannelId'
        - name: message_key
          in: body
          description: 获取消息的 key
          example: '1487667236785.0077'
          required: true
          $ref: '#/definitions/MessageKey'

  /message.create:
    post:
      description: |
        发送一条消息到指定聊天会话。
      authentication: true
      responses:
        201:
          schema:
            $ref: '#/definitions/Message'
          example: |
            {
              "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"
            }
        # TODO error responses
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: vchannel_id
          in: body
          description: 指定的目标聊天会话 id
          example: '=bw52O'
          required: true
          schema:
            $ref: '#/definitions/VChannelId'
        - name: text
          in: body
          description: 消息内容
          example: '中午吃啥啊？'
          required: true
          type: string
        - name: attachments
          in: body
          description: 消息附件
          required: true
          type: array
          items:
            $ref '#/definitions/MessageAttachment'

  /message.delete:
    post:
      description: |
        删除一条消息。
      authentication: true
      responses:
        204:
          schema:
            $ref: '#/definitions/OK'
        # TODO error responses
        default:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: message_key
          in: body
          description: 删除的消息 key
          example: '1487667236785.0077'
          required: true
          $ref: '#/definitions/MessageKey'

  /message.update_text:
    patch:
      description: |
        更新一条消息的内容。
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/Message'
          example: |
            {
              "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:
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: message_key
          in: body
          description: 更新的消息 key
          example: '1487667236785.0077'
          required: true
          $ref: '#/definitions/MessageKey'
        - name: text
          in: body
          description: 更新的消息内容
          example: '中午吃啥啊？'
          required: true
          type: string

  #---------------------------------------------------------------------------
  # 团队自定义 emoji 相关
  #---------------------------------------------------------------------------

  /emoji.list:
    get:
      description: |
        返回团队内的自定义 emoji 列表
      authentication: true
      responses:
        200:
          schema:
            type: array
            items:
              $ref: '#/definitions/Emoji'
          example: |
            [
              {
                "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"
              }
            ]

  #---------------------------------------------------------------------------
  # 团队自定义 sticker 相关
  #---------------------------------------------------------------------------

  /sticker.list:
    get:
      description: |
        返回当前用户的自定义 sticker 列表
      authentication: true
      responses:
        200:
          schema:
            type: array
            items:
              $ref: '#/definitions/StickerPack'
          example: |
            [
              {
                "pack": "黑白熊静态",
                "stickers": [
                  {
                    "url": "https://dn-bearychat.qbox.me/sticker-gif-20.gif",
                    "name": "累",
                    "width": 240,
                    "height": 240
                  }
                ]
              }
            ]

  #---------------------------------------------------------------------------
  # RTM 相关
  #---------------------------------------------------------------------------

  /rtm.start:
    post:
      description: |
        打开 RTM 连接会话
      authentication: true
      responses:
        200:
          schema:
            $ref: '#/definitions/RTMStart'
          example: |
            {
              "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
                }
              }
            }
        # TODO permission denied error
        default:
          schema:
            $ref: '#/definitions/Error'

definitions:
  VChannelId:
    description: '聊天会话 id'
    type: string
  VChannelType:
    description: '聊天会话类型'
    type: string
    enum:
      - 'normal'  # 普通讨论组聊天
      - 'session' # 临时讨论组聊天
      - 'p2p'  # 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: 团队邮箱域名
        # TODO nullable field in swagger?
        type: string
      logo_url:
        description: 团队头像地址
        type: string
      description:
        description: 团队简介
        type: string
      plan:
        $ref: '#/definitions/TeamPlan'
      created:
        description: 团队创建时间
        type: dateTime
  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:
        description: 用户所属团队 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'  # BearyBot 小助手
          - 'hubot'  # hubot 类型机器人用户
      role:
        description: 用户在团队内的身份
        type: string
        enum:
          - 'owner'  # 团队所有者
          - 'admin'  # 团队管理员
          - 'normal'  # 团队普通成员
          - 'visitor'  # 团队访客
      avatars:
        description: 用户头像
        $ref: '#/definitions/UserAvatar'
      profile:
        description: 用户个人资料
        $ref: '#/definitions/UserProfile'
      inactive:
        description: 用户是否已注销
        type: boolean
      created:
        description: 用户加入时间
        type: dateTime
  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:
        description: 讨论组创建者 id
        $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:
      # TODO add all subtypes
      - '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:
        description: 消息唯一索引 key
        $ref: '#/definitions/MessageKey'
      team_id:
        $ref: '#/definitions/ResponseObjectId'
      uid:
        description: 消息发送用户 id，为 null 时表示消息不是由 User 所发
        $ref: '#/definitions/ResponseObjectId'
      robot_id:
        description: 消息发送机器人 id，为 null 时表示消息不是由 Robot 所发
        $ref: '#/definitions/ResponseObjectId'
      vchannel_id:
        description: 消息所属聊天会话 id
        $ref: '#/definitions/VChannelId'
      refer_key:
        description: 消息引用的消息 key
        $ref: '#/definitions/MessageKey'
      subtype:
        description: 消息类型
        $ref: '#/definitions/MessageSubtype'
      text:
        description: 消息正文
        type: string
      fallback:
        description: 消息提醒使用正文
        type: string
      attachments:
        description: 消息附件
        type: array
        items:
          $ref: '#/definitions/MessageAttachment'
      created:
        description: 消息创建时间
        type: dateTime
      created_ts:
        description: 消息创建时间戳
        type: integer
        format: int32
      updated:
        description: 消息最后修改时间
        type: dateTime
      is_channel:
        description: 消息是否为讨论组消息？
        type: boolean

  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: int32
      to-ts:
        description: 区间结束的消息时间戳
        type: int32
      forward:
        description: 向前获取 n 条消息
        type: int32
      backward:
        description: 向后获取 n 条消息
        type: 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: int32
      forward:
        description: 向前获取 n 条消息
        type: int32
      backward:
        description: 向后获取 n 条消息
        type: int32

  MessageQueryLatest:
    description: |
      获取该 vchannel 下的最新消息列表
      查询结果最多返回 100 条消息：
        - limit 最大值为 100
        - 不指定 limit 时，limit 默认为 20
    properties:
      limit:
        description: 获取 n 条消息
        type: int32

  MessageQuery:
    description: |
      window / since / latest / thread 只能存在其中一种查询方法
      如果带有多种查询方法，则只以第一个方法为准
    properties:
      window:
        description: 按照 `window` 方法查询
        $ref: '#/definitions/MessageQueryWindow'
      since:
        description: 按照 `since` 方法查询
        $ref: '#/definitions/MessageQuerySince'
      latest:
        description: 按照 `latest` 方法查询
        $ref: '#/definitions/MessageQueryLatest'

  MessageQueryResult:
    required:
      - messages
    properties:
      messages:
        description: 查询到的消息列表
        type: array
        items:
          $ref: '#/definitions/Message'

  RTMStart:
    required:
      - user
      - ws_host
    properties:
      user:
        description: rtm 用户
        $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: dateTime
      updated:
        description: 最后修改时间
        type: dateTime
      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
      height:
        description: 图片高度
        type: integer

  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'
  OK:
    required:
      - code
      - error
    properties:
      code:
        $ref: '#/definitions/ResponseCode'
        default: 0

  TBD:
    description: '待定义'
    type: string

  ResponseObjectId:
    type: string
  ResponseCode:
    type: integer
    format: int32
  ResponseError:
    type: string
    format: string