通知
RTM 1.x 将于近期下架，各版本退休日期和替代方案详见 退休政策 。
文档中心
云信令（原实时消息）
Console 官网 社区 技术支持
简体中文
search-icon

消息发送 RESTful API

更新时间 2023/01/12 06:11:32

认证

云信令（原实时消息）RESTful API 仅支持 HTTPS 协议。

如果你使用 basic HTTP 认证，则可以通过服务端使用任意用户 ID 发送点对点消息或频道消息。如果你使用 Token 认证，则只能通过服务端使用生成 RTM Token 时使用的用户 ID 发送点对点消息或频道消息。
如果你的业务场景中要求服务端到客户端的消息延时必须小于 200 ms，声网建议你使用 RTM Linux C++ SDK 或 RTM Linux Java SDK 实现服务端消息发送。

Basic HTTP 认证

云信令（原实时消息）RESTful API 仅支持 HTTPS 协议。发送请求时，你需要提供 api_key:api_secret 通过 basic 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.agora.io。

如果向该域名发起 RESTful API 请求失败，请参考 使用双域名。
  • 请求：请求的格式详见下面各个 API 中的示例
  • 响应：响应内容的格式为 JSON
  • 基本 URL：https://api.agora.io/dev/v2/project/<appid>
<appid> 是你的 RTM 项目使用的 App ID。所有的请求 URL 和请求包体内容都是区分大小写的。

发送点对点消息 API（POST）

  • 方法：POST
  • 接入点：/rtm/users/<user_id>/peer_messages

通过服务端发送点对点消息。你不需要对发送消息的用户进行登录操作。

调用频率限制

对于每个 App ID，发送点对点消息 API 和发送频道消息 API 的频率上限之和是 500 次每秒。

调用时序

下图展示了应用服务端向 RTM SDK 发送点对点消息的流程。

wait_for_ack 参数设为 true 且接收端在线

wait_for_ack 参数设为 false

参数

URL 参数

此 API 需要在 URL 中传入以下参数。

参数 类型 描述
user_id String RTM 系统中发送点对点消息的用户 ID。最大长度为 64 个可见字符。不能是空字符串。以下为支持的字符集范围:
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",","'"
作为 URL 参数，user_id 开头和结尾的字符不能是空格。

查询参数

此 API 需要传入以下查询参数。

参数 类型 描述
wait_for_ack Boolean （可选）此 API 是否等到声网 RTM 系统确认消息投递成功之后再返回响应。默认为 false。
  • true：代表此 API 会等到声网 RTM 系统确认消息投递成功之后再返回响应。如果消息投递成功会返回 “message delivered”。
  • false：代表此 API 会在声网 RTM 系统收到消息后立即返回响应，而不会确认消息是否投递成功。如果消息发送成功会返回 “message sent”。

请求包体参数

该 API 需要在请求包体中传入以下参数。

参数 类型 描述
destination String RTM 系统中接收点对点消息的用户 ID。最大长度为 64 个可见字符。不能是空字符串。以下为支持的字符集范围:
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",","'"
enable_offline_messaging Boolean
自 RTM SDK 全平台 v1.5.0 开始，离线消息功能正式下线。旧版本 SDK 会继续支持该功能，已集成该功能的用户不受影响。
（可选）是否开启离线消息。默认值是 false。
  • true: 开启离线消息。如果在你发送消息时，接收消息的用户不在线，消息服务器会保存这条消息。接收消息的用户登录之后会收到此消息。每个接收端最多保存 200 条离线消息，最长保存七天。当保存的离线消息超出限制时，最新的消息会替换最老的消息。
  • false: 不开启离线消息。
enable_historical_messaging Boolean （暂不支持）（可选）是否保存为历史消息。默认值是 false。
  • true：保存为历史消息。你可以使用历史消息 RESTful API 查询历史消息。
  • false: 不保存为历史消息。
payload String 点对点消息内容。不能为空字符串，长度最大 32 KB。

响应包体参数

该 API 在响应包体中返回以下参数：

参数 类型 描述
result String 请求结果。
  • "success"：请求成功。
  • "failed"：请求失败。
request_id String 标识此次请求的唯一 ID。
code String 消息发送状态。
  • "message_sent": 消息已发送。
  • "message_delivered": 接收端已收到消息。
  • "message_offline": 接收端离线。

请求示例

  • 请求 URL：

      https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/users/userA/peer_messages?wait_for_ack=true

  • Content-type 为 application/json;charset=utf-8

  • Authorization 可以是 Basic HTTP 认证或 Token 认证，生成方法请参考 RESTful API 认证。

  • 请求包体内容

{
    "destination": "userB",
    "enable_offline_messaging": false,
    "enable_historical_messaging": false,
    "payload": "Hello"
}

响应示例

消息已发送：

{
    "code": "message_sent",
    "result": "success",
    "request_id": "123"
}

接收端已收到消息：

{
    "code": "message_delivered",
    "result": "success",
    "request_id": "123"
}

接收端离线：

{   
    "code": "message_offline",
    "request_id": "123"
}

发送频道消息 API（POST）

  • 方法：POST
  • 接入点：/rtm/users/<user_id>/channel_messages

通过服务端发送频道消息。你不需要对发送消息的用户进行登录和加入频道操作。

调用频率限制

对于每个 App ID，发送点对点消息 API 和发送频道消息 API 的频率上限之和是 500 次每秒。

参数

URL 参数

此 API 需要在 URL 中传入以下参数。

参数 类型 描述
user_id String RTM 系统中发送频道消息的用户 ID。最大长度为 64 个可见字符。不能是空字符串。以下为支持的字符集范围:
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",","'"
作为 URL 参数，user_id 开头和结尾的字符不能是空格。

请求包体参数

该 API 需要在请求包体中传入以下参数：

参数 类型 描述
channel_name String 接收频道消息的 RTM 频道名。最大长度为 64 个可见字符。不能是空字符串。以下为支持的字符集范围:
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",","'"
enable_historical_messaging Boolean （可选）是否保存为历史消息。默认值是 false。
  • true：保存为历史消息。你可以使用历史消息 RESTful API 查询历史消息。
  • false: 不保存为历史消息。
payload String 频道消息内容。不能为空字符串，长度最大 32 KB。

响应包体参数

该 API 在响应包体中返回以下参数：

参数 类型 描述
code String 消息发送状态。
  • "message_sent": 消息已发送。
    		•
    result String 请求结果。
    • "success"：请求成功。
    • "failed"：请求失败。
    request_id String 标识此次请求的唯一 ID。

    请求示例

    • 请求 URL：

        https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/users/userA/channel_messages

    • Content-type 为 application/json;charset=utf-8

    • Authorization 可以是 Basic HTTP 认证或 Token 认证，生成方法请参考 RESTful API 认证。

    • 请求包体内容

    {
    "channel_name":"channelA",
    "enable_historical_messaging": false,
    "payload": "Hello"
}

    响应示例

    {
    "code": "message sent",
    "request_id": "123",
    "result": "success"
}

    响应状态码

    状态码 描述
    200 请求成功。
    400 请求参数错误，请根据返回提示检查。
    401 用户权限错误。
    408 服务器请求超时，建议稍后重试。
    429 单位时间内请求过多。
    500 服务器内部错误。