Documentation Powered by ReDoc

Houge REST RESTful 接口 (1.0.0)

Download OpenAPI specification:Download

Houge REST 所有开放的接口都在本文件内进行定义，文件详细描述了接口的名称、约束及作用范围，请严格按照文档的要求在适合的环境中调用相应的接口。

  • 以 /- 为前缀的路径是系统内部的 API，用于获取应用基础信息，或者保证应用正常运行的支持接口设计。
  • 以 /i 为前缀的路径是服务内部的 API，为业务服务端设计，该路径下的所有接口应该是在安全可信的环境下调用执行。
  • 以 /p 为前缀的路径是公共的 API，可在所有环境下调用执行。

Authentication

AccessToken

访问令牌

Security Scheme Type API Key
Query parameter name: access_token

Basic

Security Scheme Type HTTP
HTTP Authorization Scheme Basic

SUPPORT

系统支撑

应用信息

Responses

Response samples

Content type
application/json
{
  • "app": {
    },
  • "java": {
    }
}

应用健康状况

Responses

Response samples

Content type
application/json
{
  • "status": "UP"
}

为指定用户生成访问令牌

Authorizations:
Basic
path Parameters
uid
required
integer <int64>

用户 ID

Responses

Response samples

Content type
application/json
{
  • "access_token": "string"
}

创建用户

在 Houge 系统中创建可用于聊天的用户。

Authorizations:
Basic
Request Body schema: application/json

请求体中的 uid 与 origin_uid 字段二选一, 如果传入的 uid 值则会直接映射到 Houge 系统中用户的 ID， 该方式可以保证业务系统中的用户 ID 与 Houge 系统中的用户 ID 相同。如果传入 origin_uid 值 IM 系统 会在内部映射一个数字类型的 uid 值并返回。

uid
integer <int64>

全局唯一的用户 ID，如果业务方手动传入则调用者必须保证其唯一性

origin_uid
string

调用者系统内部的唯一用户 ID，如果业务方手动传入则调用者必须保证其唯一性

Responses

Request samples

Content type
application/json
{
  • "uid": 0,
  • "origin_uid": "string"
}

Response samples

Content type
application/json
{
  • "uid": 0
}

创建群组

在 Houge 系统中创建可用于多人聊天的群组，群组创建成功后创建者（creator_id）将自动加入为该群的成员。

Authorizations:
Basic
Request Body schema: application/json

请求体中的 gid 是非必须字段。如果业务方传入了 gid 值，IM 将会使用其作为 Houge 系统内部群组ID，反之 Houge 系统会自动生成一个全局唯一的群组 ID。

gid
integer <int64>

全局唯一的群组 ID，如果业务方手动传入则调用者必须保证其唯一性

creator_id
required
integer <int64>

群组创建者，必须映射一个 IM 系统中已经存在的用户 IM

Responses

Request samples

Content type
application/json
{
  • "gid": 0,
  • "creator_id": 0
}

Response samples

Content type
application/json
{
  • "gid": 0
}

删除指定的群组

删除指定群组并解除群成员关系。

Authorizations:
Basic
path Parameters
gid
required
integer <int64>

群组 ID

Responses

将用户添加为指定群组的成员

Authorizations:
Basic
path Parameters
gid
required
integer <int64>

群组 ID

Request Body schema: application/json
uid
required
integer <int64>

IM 系统中已经存在的用户 ID

Responses

Request samples

Content type
application/json
{
  • "uid": 0
}

将用户与指定群组的成员关系解除

Authorizations:
Basic
path Parameters
gid
required
integer <int64>

群组 ID

Request Body schema: application/json
uid
required
integer <int64>

IM 系统中已经存在的用户 ID

Responses

Request samples

Content type
application/json
{
  • "uid": 0
}

MESSAGE

IM 消息

获取 IM 消息 ID

返回 IM 消息 ID 列表，该列表中的 ID 用于在后续聊天消息中使用，每个 ID 仅可使用一次。

Authorizations:
AccessToken
query Parameters
limit
integer <int32> [ 1 .. 100 ]

返回 ID 的最大数量

Responses

Response samples

Content type
application/json
[
  • "string"
]

获取指定时间以后的消息

如果返回的消息数组的长度小于 limit 请求查询参数值，则代表服务端没有更多的消息不需要继续查询，反之则 代表服务端还有更多的消息，客户端需要继续调用些接口拉取私聊信息，直到消息数组的长度小于 limit。

Authorizations:
AccessToken
query Parameters
begin_time
string <date-time>

查询 begin_time 之后（包含 begin_time）接收到的消息。

默认仅支持查询3天（72小时）以内的消息查询，时间超出范围将默认将 begin_time 设置为可查询的最早时间。

offset
integer <int32>

查询偏移量

limit
integer <int32> [ 1 .. 500 ]

返回最大的条数

Responses

Response samples

Content type
application/json
[
  • {
    }
]

发送用户消息

Authorizations:
AccessToken
Request Body schema: application/json
uid
required
integer <int64>

消息接收的用户 ID

content
required
string <= 4096 characters

消息内容

content_type
integer <int32>
Default: 0
Enum: 0 1 2 3

消息内容类型

  • 0 普通文本消息
  • 1 图片消息
  • 2 语音消息
  • 3 视频消息
extra_args
string <= 2048 characters

扩展参数将原样转发至客户端

Responses

Request samples

Content type
application/json
{
  • "uid": 0,
  • "content": "string",
  • "content_type": 0,
  • "extra_args": "string"
}

Response samples

Content type
application/json
{
  • "message_id": "7K7KJKK56K23OMY"
}

发送群组消息

Authorizations:
AccessToken
Request Body schema: application/json
gid
required
integer <int64>

消息接收的群组 ID

content
required
string <= 4096 characters

消息内容

content_type
integer <int32>
Default: 0
Enum: 0 1 2 3

消息内容类型

  • 0 普通文本消息
  • 1 图片消息
  • 2 语音消息
  • 3 视频消息
extra_args
string <= 2048 characters

扩展参数将原样转发至客户端

Responses

Request samples

Content type
application/json
{
  • "gid": 0,
  • "content": "string",
  • "content_type": 0,
  • "extra_args": "string"
}

Response samples

Content type
application/json
{
  • "message_id": "7K7KJKK56K23OMY"
}

批量更新消息已读状态

Authorizations:
AccessToken
Request Body schema: application/json
message_ids
required
Array of strings <= 100 items

消息 ID 列表，同时最大支持 100 条消息的已读状态更新

Responses

Request samples

Content type
application/json
{
  • "message_ids": [
    ]
}