RTM 1.x 将于近期下架，各版本退休日期和替代方案详见退休政策。

文档中心





云信令（原实时消息）

Console 官网社区技术支持





服务端

平台

Android

iOS

macOS

Web

Windows

Linux

框架

小程序

Unity

服务端

事件与历史消息查询 RESTful API

更新时间 2023/03/13 03:11:27

事件与历史消息查询 RESTful API 目前支持以下功能：

查询用户事件和频道事件。
查询历史消息。
自 RTM SDK 全平台 v1.5.0 开始，历史消息功能正式下线。旧版本 SDK 会继续支持该功能，已集成该功能的用户不受影响。

认证

你可以选择 HTTP 基本认证或 Token 认证。云信令（原实时消息） RESTful API 仅支持 HTTPS 协议。

HTTP 基本认证

云信令（原实时消息） RESTful API 仅支持 HTTPS 协议。发送请求时，你需要提供 api_key:api_secret 通过 HTTP 基本认证并填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 RESTful API 认证。

Token 认证

你需要在发送 HTTP 请求时在 HTTP 请求头部的 x-agora-token 字段和 x-agora-uid 字段分别填入：

服务端生成的 RTM Token。
生成 RTM Token 时使用的 uid。

具体生成 x-agora-token 字段和 x-agora-uid 字段的方法请参考 RESTful API 认证。

API 调用步骤

查询用户事件和频道事件

查询用户上线或下线事件：直接调用获取用户上线或下线事件 API。
查询用户加入或离开频道事件：直接调用获取用户加入或离开频道事件 API。

查询历史消息

查询历史消息：先调用创建历史消息查询资源 API，再调用获取历史消息 API。
查询历史消息数目：直接调用获取历史消息数目 API。

数据格式

所有的请求都发送给域名：api.agora.io。

如果向该域名发起 RESTful API 请求失败，请参考使用双域名。

请求：请求的格式详见下面各个 API 中的示例
响应：响应内容的格式为 JSON
基本 URL：https://api.agora.io/dev/v2/project/<appid>

<appid> 是你的 RTM 项目使用的 App ID。所有的请求 URL 和请求包体内容都是区分大小写的。

用户与频道事件 API

获取用户上线或下线事件 API（GET）

该方法从声网 RTM 服务器指定的地址获取用户上线或下线事件。已经获取的事件会从声网 RTM 服务器中移除，你无法再次获取。

每个 App ID 每秒钟的请求数不能超过 10 次。

对于每个 App ID，RTM 后台最多存储 2000 条事件。如果事件超过 2000 条，最老的事件会被最新的事件替换。

单次返回最多 1000 条事件。

声网对事件按地理区域缓存，因此不保证来自不同地理区域的事件顺序的正确性。

声网只在同一地理区域内同步事件，不在地理区域间同步。所以，你从某地理区域发起请求拉取了事件后，如果你从另一个区域再次发起请求可能会得到相同的事件。

方法：GET
接入点：/rtm/vendor/user_events

请求示例

请求 URL：

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/vendor/user_events

请求参数

此 API 无请求参数。

响应示例

{
  "result": "success",
  "request_id": "10116762670167749259",
  "events": [
    {
      "ms": 1578027420761,
      "type": "Login",
      "user_id": "rtmtest_RTM_4852_4857w7%"
    }
  ]
}

响应参数

参数	类型	描述
`result`	string	本次请求结果。
`request_id`	string	本次请求唯一的 ID。
`events`	JSON	用户上线下线事件。

events 的成员包含以下内容：

参数	类型	描述
`ms`	int	从 1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的毫秒数。
`type`	string	事件类型： `Login`: 用户登录（上线）事件。 `Logout`: 用户登出（下线）事件。
`user_id`	string	本次事件对应的用户名。

获取用户加入或离开频道事件 API（GET）

该方法从声网 RTM 服务器指定的地址获取用户加入或离开频道事件。已经获取的事件会从声网 RTM 服务器中移除，你无法再次获取。

每个 App ID 每秒钟的请求数不能超过 10 次。

对于每个 App ID，RTM 系统最多存储 2000 条事件。如果事件超过 2000 条，最老的事件会被最新的事件替换。

单次返回最多 1000 条事件。

声网对事件按地理区域缓存，因此不保证来自不同地理区域的事件顺序的正确性。

声网只在同一地理区域内同步事件，不在地理区域间同步。所以，你从某地理区域发起请求拉取了事件后，如果你从另一个区域再次发起请求可能会得到相同的事件。

方法：GET
接入点：/rtm/vendor/channel_events

请求示例

请求 URL：

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/vendor/channel_events

请求参数

此 API 无请求参数。

响应示例

{
  "result": "success",
  "request_id": "10116762670167749259",
  "events": [
    {
      "group_id": "example_channel_id",
      "ms": 1578027418981,
      "type": "Join",
      "user_id": "userA"
    }
  ]
}

参数	类型	描述
`result`	string	本次请求结果。
`request_id`	string	本次请求唯一的 ID。
`events`	JSON Array	加入退出频道事件。

响应参数

events 的成员包含以下内容：

参数	类型	描述
`group_id`	string	本次事件对应的频道名。
`ms`	int	从 1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的毫秒数。
`type`	string	事件类型： `Join`: 用户加入频道事件。 `Leave`: 用户离开频道事件。
`user_id`	string	本次事件对应的用户名。

响应状态码

错误码	描述
200	请求成功。
400	请求的语法错误。
408	服务器请求超时或服务器无响应。
429	单位时间内请求过多。

历史消息 API

创建历史消息查询资源 API（POST）

该方法向声网 RTM 服务器申请历史消息查询资源。若请求成功，你可以通过获取历史消息 API从服务器返回的 location 获取查询到的历史消息。

如果需要将某条点对点或频道消息存为历史消息，你必须在调用 sendMessage 或 sendMessageToPeer 时将 sendMessageOptions 类中的 enableHistoricalMessaging 成员变量设为 true。否则你无法通过 RESTful API 查询到这条历史消息。

历史消息默认保留七天，单个 App ID 的默认存储空间限制为 2 GB，一般足够支持数万日活应用的消息量。如果需要延长保留时间或提高存储空间，请联系技术支持。

当前版本仅支持文本消息，不支持自定义二进制消息。

对于每个 App ID，每秒请求数不能超过 100 次。

方法：POST
接入点：/rtm/message/history/query

请求示例

请求 URL：

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/query

请求参数

请求包体的参数如下：

参数	类型	描述
`filter`	JSON	筛选条件。
`offset`	int	（可选）需要返回的历史消息起始序号偏移量。默认值为 0，即不发生偏移，获取历史消息 API 从第一条消息开始返回。如果设为 1，则偏移值为 1，获取历史消息 API 从第二条消息开始返回。返回的消息数为 `limit` 的值。
`limit`	int	（可选）单次返回的历史消息条数。可选值：（默认）20 50 100 如果历史消息数量大于单次返回的历史消息条数，你可以通过 `offset` 设置偏移量，获取其余的历史消息。
`order`	string	（可选）排序方法 `asc`（默认）：按时间顺序。 `desc`：按时间倒序。

filter 中需要填写的内容如下：

参数	类型	描述
`source`	string	（可选）消息发送方，必须是用户。如果此参数不赋值，则 API 会筛选出消息接收方在指定时间段内收到的所有消息。
`destination`	string	（可选）消息接收方，可以是用户或频道。如果此参数不赋值，则 API 会筛选出消息发送方在指定时间段内发送的所有消息。
`start_time`	string	历史消息查询起始时间。时间为 UTC 时间，使用 ISO8601 标准。时间的格式为 `yyyy-mm-ddThh:mm:ssZ` ，例如 `2019-08-01T01:24:10Z`。`Z` 代表时间偏移量为 0，即为 UTC 时间。
`end_time`	string	历史消息查询结束时间。时间为 UTC 时间，使用 ISO8601 标准。时间的格式为 `yyyy-mm-ddThh:mm:ssZ` ，例如 `2019-08-01T01:24:10Z`。`Z` 代表时间偏移量为 0，即为 UTC 时间。

频道只能作为 destination。API 的筛选规则与 source 和 destination 的关系详见下表：

`source`	`destination`	筛选规则
不赋值	userA	API 会筛选出 userA 在指定时间段内收到的所有消息，包括点对点消息和频道消息。
不赋值	channelA	API 会筛选出 channelA 在指定时间段内收到的所有频道消息。
userA	不赋值	API 会筛选出 userA 在指定时间段内发送的所有消息，包括点对点消息和频道消息。
userA	userB	API 会筛选出 userA 在指定时间段内发送给 userB 的所有点对点消息。
userA	channelA	API 会筛选出 userA 在指定时间段内发送到 channelA 的所有频道消息。

start_time 和 end_time 仅支持 UTC 时间，不支持时区和夏令时。如果你的本地时间不是 UTC 时间，你需要先将本地时间转换为 UTC 时间。例如，如果你的本地时间是 2019-08-01T09:24:10，时区为东八区（UTC/GMT+08:00），则 UTC 时间应为 2019-08-01T01:24:10Z。

请求示例

下面的示例从第 101 条消息开始返回，单次返回 20 条消息，消息排序为按时间顺序。

userA 在指定时间段内收到的所有消息

{
  "filter": {
    "destination": "userA",
    "start_time": "2019-08-01T01:22:10Z",
    "end_time": "2019-08-01T01:32:10Z"
  },
  "offset": 100,
  "limit": 20,
  "order": "asc"
}

channelA 在指定时间段内收到的所有消息

{
  "filter": {
    "destination": "channelA",
    "start_time": "2019-08-01T01:22:10Z",
    "end_time": "2019-08-01T01:32:10Z"
  },
  "offset": 100,
  "limit": 20,
  "order": "asc"
}

userA 在指定时间段内发送的所有消息

{
  "filter": {
    "source": "userA",
    "start_time": "2019-08-01T01:22:10Z",
    "end_time": "2019-08-01T01:32:10Z"
  },
  "offset": 100,
  "limit": 20,
  "order": "asc"
}

userA 在指定时间段内发送给 userB 的所有点对点消息

{
  "filter": {
    "source": "userA",
    "destination": "userB",
    "start_time": "2019-08-01T01:22:10Z",
    "end_time": "2019-08-01T01:32:10Z"
  },
  "offset": 100,
  "limit": 20,
  "order": "asc"
}

userA 在指定时间段内发送到 channelA 的所有频道消息

{
  "filter": {
    "source": "userA",
    "destination": "channelA",
    "start_time": "2019-08-01T01:22:10Z",
    "end_time": "2019-08-01T01:32:10Z"
  },
  "offset": 100,
  "limit": 20,
  "order": "asc"
}

响应示例

{
  "result": "success",
  "offset": 100,
  "limit": 20,
  "order": "asc",
  "location": "~/rtm/message/history/query/123456123456"
}

响应参数

响应包体的参数如下：

参数	类型	描述
`result`	string	请求结果。
`offset`	int	当前时间段内的消息偏移量。
`limit`	int	单次返回的历史消息条数。
`location`	string	历史消息资源地址。你可以从这个 URL 调用获取历史消息 API 获取查询结果。

获取历史消息 API（GET）

该方法从创建历史消息查询资源 API 返回的查询资源 URL 获取历史消息。如果你已经通过某个查询资源 URL 获取了历史消息，则此查询资源 URL 会失效。你无法通过某个查询资源 URL 重复获取历史消息。

历史消息默认保留七天，单个 App ID 的默认存储空间限制为 2 GB，一般足够支持数万日活应用的消息量。如果需要延长保留时间或提高存储空间，请联系技术支持。

当前版本仅支持文本消息，不支持自定义二进制消息。

对于每个 App ID，每秒请求数不能超过 100 次。

方法：GET
接入点：/rtm/message/history/query/$handle
请求 URL：

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/query/$handle

请求参数

此 API 需要下列 URL 参数：

参数	类型	描述
`$handle`	string	创建历史消息查询资源 API 返回的 `location` 字段中 `~/rtm/message/history/query/` 后面的部分。例如，如果`location` 返回 `"~/rtm/message/history/query/123456123456"`，则 `$handle` 为 `123456123456`。

请求示例

$handle 为 123456123456：

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/query/123456123456

响应示例

{
  "code": "ok",
  "messages": [
    {
      "dst": "dst",
      "message_type": "peer_message",
      "ms": 1587009745719,
      "payload": "123",
      "src": "src"
    }
  ],
  "request_id": "125877_12008901591665642856",
  "result": "success"
}

响应参数

响应包体的参数如下：

参数	类型	描述
`result`	string	本次请求结果。
`code`	string	资源准备情况： `ok`：资源准备完成。 `in progress`：资源还未准备完成，请稍后重试。当服务器返回 `in progress` 时，请等待 2 秒再发起请求。
`message`	JSON	历史消息列表。

messages 的成员包含以下参数：

参数	类型	描述
`src`	string	消息发送方。
`dst`	string	消息接收方。
`message_type`	string	消息类型。可以是 `peer_message` 或 `channel_message`。
`payload`	string	消息体。当前版本仅支持文本消息。
`ms`	int	从 1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的毫秒数。

获取历史消息数目 API（GET）

该方法从声网 RTM 服务器指定的地址获取历史消息数目。

历史消息默认保留七天，单个项目的默认存储空间限制为 2 GB。

当前版本仅支持文本消息，不支持自定义二进制消息。

对于每个 App ID，每秒请求数不能超过 100 次。

方法：GET
接入点：/rtm/message/history/count

请求示例

请求 URL：

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/count

请求参数

请求的查询参数如下：

参数	类型	描述
`source`	string	（可选）消息发送方，必须是用户。如果此参数不赋值，则 API 会筛选出消息接收方在指定时间段内收到的所有消息。
`destination`	string	（可选）消息接收方，可以是用户或频道。如果此参数不赋值，则 API 会筛选出消息发送方在指定时间段内发送的所有消息。
`start_time`	string	历史消息查询起始时间。时间为 UTC 时间，使用 ISO8601 标准。时间的格式为 `yyyy-mm-ddThh:mm:ssZ` ，例如 `2019-08-01T01:24:10Z`。`Z` 代表时间偏移量为 0，即为 UTC 时间。
`end_time`	string	历史消息查询结束时间。时间为 UTC 时间，使用 ISO8601 标准。时间的格式为 `yyyy-mm-ddThh:mm:ssZ` ，例如 `2019-08-01T01:24:10Z`。`Z` 代表时间偏移量为 0，即为 UTC 时间。

频道只能作为 destination。API 的筛选规则与 source 和 destination 的关系详见下表：

`source`	`destination`	筛选规则
不赋值	userA	API 会筛选出 userA 在指定时间段内收到的所有消息，包括点对点消息和频道消息。
不赋值	channelA	API 会筛选出 channelA 在指定时间段内收到的所有频道消息。
userA	不赋值	API 会筛选出 userA 在指定时间段内发送的所有消息，包括点对点消息和频道消息。
userA	userB	API 会筛选出 userA 在指定时间段内发送给 userB 的所有点对点消息。
userA	channelA	API 会筛选出 userA 在指定时间段内发送到 channelA 的所有频道消息。

start_time 和 end_time 仅支持 UTC 时间，不支持时区和夏令时。如果你的本地时间不是 UTC 时间，你需要先将本地时间转换为 UTC 时间。例如，如果你的本地时间是 2019-08-01T09:24:10，时区为东八区（UTC/GMT+08:00），则 UTC 时间应为 2019-08-01T01:24:10Z。

请求示例

userA 在指定时间段内收到的所有消息

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/count?&destination="userA"&start_time=2019-08-01T01:22:10Z&end_time=2019-08-01T01:24:10Z

channelA 在指定时间段内收到的所有消息

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/count?&destination="channelA"&start_time=2019-08-01T01:22:10Z&end_time=2019-08-01T01:24:10Z

userA 在指定时间段内发送的所有消息

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/count?source="userA"&start_time=2019-08-01T01:22:10Z&end_time=2019-08-01T01:24:10Z

userA 在指定时间段内发送给 userB 的所有点对点消息

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/count?source="userA"&destination="userB"&start_time=2019-08-01T01:22:10Z&end_time=2019-08-01T01:24:10Z

userA 在指定时间段内发送到 channelA 的所有频道消息

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/message/history/count?source="userA"&destination="channelA"&start_time=2019-08-01T01:22:10Z&end_time=2019-08-01T01:24:10Z

响应示例

{
  "result": "success",
  "code": "ok",
  "count": 123
}

响应参数

参数	类型	描述
`result`	string	本次请求结果。
`code`	string	资源准备情况： `ok`：资源准备完成。 `in progress`：资源还未准备完成，请稍后重试。当服务器返回 `in progress` 时，请等待 2 秒再发起请求。
`count`	int	历史消息数目。

响应状态码

错误码	描述
200	请求成功。
400	请求的语法错误。
408	服务器请求超时或服务器无响应。
429	单位时间内请求过多。

这篇文章对你有帮助吗？

是

否