消息发送 RESTful API

认证

Basic HTTP 认证

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

Token 认证

如果你已经在服务端生成了 RTM Token，你也可以选用 token 认证。你需要在发送 HTTP 请求时在 HTTP 请求头部的 x-ar-token 字段和 x-ar-uid 字段分别填入：

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

示例代码

下面的 Java 示例代码展示了如何实现 token 认证。

Request request = new Request.Builder()
...
// 在 HTTP 请求头部的 x-ar-token 字段填入获取的 RTM Token
.addHeader("x-ar-token", "<Your RTM Token>")
// 在 HTTP 请求头部的 x-ar-uid 字段填入用于生成该 RTM Token 的 uid
.addHeader("x-ar-uid", "<Your uid used to generate the RTM Token>")
...

数据格式

所有的请求都发送给域名：api.agrtc.cn。

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

发送点对点消息 API（POST）

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

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

调用频率限制

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

调用时序

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

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

wait_for_ack 参数设为 false

参数

URL 参数

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

查询参数

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

请求包体参数

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

响应包体参数

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

请求示例

• 请求 URL：

  https://api.agrtc.cn/dev/v2/project/<appid>/rtm/users/userA/peer_messages?wait_for_ack=true
  

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

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

• 请求包体内容

{
    "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 的调用频率上限是 500 次每秒。

参数

URL 参数

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

请求包体参数

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

响应包体参数

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

请求示例

• 请求 URL：

  https://api.agrtc.cn/dev/v2/project/<appid>/rtm/users/userA/channel_messages
  

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

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

• 请求包体内容

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

响应示例

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

响应状态码