跳到主要内容
版本:v2

即时通讯 REST API

概览

请求的 Base URL 可以在云服务控制台 > 设置 > 应用 Keys > 服务器地址查看。 对于 POST 和 PUT 请求,请求的主体必须是 JSON 格式,而且 HTTP Header 的 Content-Type 需要设置为 application/json。 请求的鉴权是通过 HTTP Header 里面包含的键值对来进行的,详见数据存储 REST API 使用详解中《请求格式》一节的说明。

_Conversation 表包含一些内置的关键字段定义了对话的属性、成员等,单聊、群聊、聊天室、服务号均在此表中,详见即时通讯总览的《对话》一节。 不过为了避免出现数据不一致问题,我们不推荐调用数据存储相关的 API 直接操作 _Conversation 表中的数据。

当前的 API 版本为 1.2

  • 单聊、群聊相关 API 以 rtm/conversations 标示
  • 聊天室相关 API 以 rtm/chatrooms 标示,在 _Conversation 表内用字段 tr 为 true 标示。
  • 服务号相关 API 以 rtm/service-conversations 标示,在 _Conversation 表内用字段 sys 为 true 标示。

除此之外,与 client 相关的请求以 rtm/clients 标示。 最后,一些全局性质的 API 直接以 rtm/{function} 标示,如 rtm/all-conversations 可查询所有类型的对话。

单聊、群聊

创建对话

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"name":"My First Conversation", "m": ["BillGates", "SteveJobs"], "unique": true}' \
https://{{host}}/1.2/rtm/conversations

上面的例子会创建一个最简单的对话,包括两个 client ID 为 BillGates 和 SteveJobs 的初始成员。对话创建成功会返回 objectId,即即时通讯中的对话 ID,客户端就可以通过这个 ID 发送消息了。新创建的对话可以在 _Conversation 表内找到。 对话的字段可参考即时通讯总览的《对话》一节。 传入 "unique": true 参数可以保证对话的唯一性。

返回

{
"unique":true,
"updatedAt":"2020-05-26T06:42:31.492Z",
"name":"My First Conversation",
"objectId":"5eccba570d3a42c5fd4e25c3",
"m":["BillGates","SteveJobs"],
"createdAt":"2020-05-26T06:42:31.482Z",
"uniqueId":"6c7b0e5afcae9aa1139a0afa25833dec"
}

需要注意,群聊与单聊的唯一区别是 client 数量,API 层面是一致的。

查询对话

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'where={"name": "first conversation"}' \
--data-urlencode 'skip=1' \
--data-urlencode 'limit=20' \
https://{{host}}/1.2/rtm/conversations
参数约束说明
skip可选
limit可选与 skip 联合使用实现分页
where可选参见数据存储 REST API 使用详解的《查询》一节

返回

{"results": [
{"name":"test conv1",
"m":["tom", "jerry"],
"createdAt":"2018-01-17T04:15:33.386Z",
"updatedAt":"2018-01-17T04:15:33.386Z",
"objectId":"5a5ecde6c3422b738c8779d7"}
]}

更新对话

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"name":"Updated Conversation"}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}

_Conversation 表除 m 字段均可通过这个接口更新。

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

删除对话

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/conversations/{conv_id}

返回

{}

增加成员

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["Tom", "Jerry"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/members

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

移除成员

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["Tom", "Jerry"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/members

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

查询成员

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/conversations/{conv_id}/members

返回

{"result": ["client1", "client2"]}

增加静音用户

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["Tom", "Jerry"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/mutes
参数说明
client_ids要静音的 Client ID,数组

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

移除静音用户

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["Tom", "Jerry"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/mutes

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

查询静音用户

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/conversations/{conv_id}/mutes

返回

{"result": ["client1", "client2"]}

单聊、群聊-发消息

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": ""}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/messages

注意,由于这个接口的管理性质,当你通过这个接口发送消息时,我们不会检查 from_client 是否有权限给这个对话发送消息,而是统统放行,请谨慎使用这个接口。 如果你在应用中使用了我们内部定义的富媒体消息格式,在发送消息时 message 字段需要遵守相应的格式要求。

参数约束说明
from_client必填消息的发件人 client Id
message必填消息内容(这里的消息内容的本质是字符串,但是我们对字符串内部的格式没有做限定,理论上开发者可以随意发送任意格式,只要大小不超过 5 KB 限制即可。)
transient可选是否为暂态消息,默认 false
no_sync可选默认情况下消息会被同步给在线的 from_client 用户的客户端,设置为 true 禁用此功能。
push_data可选以消息附件方式设置本条消息的离线推送通知内容。如果目标接收者使用的是 iOS 设备并且当前不在线,我们会按照该参数填写的内容来发离线推送。请参看即时通讯开发指南第二篇的《离线推送通知》一节的说明。
priority可选定义消息优先级,可选值为 high、normal、low,分别对应高、中、低三种优先级。该参数大小写不敏感,默认为中优先级 normal。本参数仅对暂态消息或聊天室的消息有效,高优先级下在服务端与用户设备的连接拥塞时依然排队。
mention_all可选布尔类型,用于提醒对话内所有成员注意本消息。
mention_client_ids可选数组类型,表示需要提醒注意本消息的对话内成员 client_id 列表,最多能包含 20 个 client Id。

返回说明:

默认情况下发送消息 API 使用异步的方式,调用后返回消息 id 和接收消息的服务器时间戳,例如 {"msg-id":"qNkRkFWOeSqP65S9fDyHJw", "timestamp":1495431811151}

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

查询历史消息

该接口要求使用 master key。 为了保证获取聊天记录的安全性,可以开启签名认证,具体可以参考即时通讯开发指南第三篇的《安全与签名》一节。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
https://{{host}}/1.2/rtm/conversations/{conv_id}/messages
参数约束说明
msgid可选起始的消息 id,使用时必须加上对应消息的时间戳 timestamp 参数,作为查询的起点
timestamp可选查询起始的时间戳。默认是当前时间,单位是毫秒
till_msgid可选查询终止的消息 id。使用时必须加上消息的时间戳 till_timestamp 参数,作为查询的终点
till_timestamp可选查询终止的时间戳,默认为 0,单位是毫秒
include_start可选是否包含由 timestamp 与 msgid 确定的起始消息。布尔值,默认为 false
include_stop可选是否包含由 till_timestamp 与 till_msgid 确定的终止消息。布尔值,默认为 false
reversed可选以默认排序(默认按时间降序)相反的方向返回结果,这时 till_timestamp 默认为当前时间戳,timestamp 默认为 0。布尔值,默认为 false
limit可选返回条数限制,可选,默认 100 条,最大 1000 条
client_id可选查看者 id(签名参数)
nonce可选签名随机字符串(签名参数)
signature_ts可选签名时间戳(签名参数),单位是毫秒
signature可选签名(签名参数)

本接口时间参数较多,这里举一示例供大家参考。比如某对话内有三条消息,id 分别为 id1、id2、id3,发消息的时间分别是 t1、t2、t3(t1 < t2 < t3),下面列举出不同参数组合的查询结果(空白表示使用默认值):

timestampmsgidtill_timestamptill_msgidinclude_startinclude_stopreversed结果
t3id3t1id1id2
t3id3t1id1trueid3 id2
t3id3t1id1trueid2 id1
t1id1t3id3trueid2
t1id1t3id3truetrueid1 id2
t1id1t3id3truetrueid2 id3

返回数据格式,JSON 数组,默认按消息记录从新到旧排序,设置请求参数 reversed 后以相反的方向排序。

返回:

[
{
"timestamp": 1408008498571,
"conv-id": "219946ef32e40c515d33ae6975a5c593",
"data": "今天天气不错!",
"from": "u111872755_9d0461adf9c267ae263b3742c60fa",
"msg-id": "vdkGm4dtRNmhQ5gqUTFBiA",
"is-conv": true,
"is-room": false,
"to": "5541c02ce4b0f83f4d44414e",
"bin": false,
"from-ip": "202.117.15.217"
},
...
]

如需查询某个用户发出的消息,可以调用 GET /rtm/clients/{client_id}/messages 这个接口。 如需查询整个应用的历史消息,可以调用 GET /rtm/messages 这个接口。

单聊、群聊-修改消息

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": "", "timestamp": 123}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/messages/{message_id}
参数约束说明
from_client必填消息的发件人 client ID
message必填消息体
timestamp必填消息的时间戳

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

单聊、群聊-撤回消息

该接口要求使用 master key。需要相应 SDK 的支持,具体可参考之前的修改消息接口。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "timestamp": 123}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/messages/{message_id}/recall
参数约束说明
from_client必填消息的发件人 client ID
timestamp必填消息的时间戳

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

删除消息

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'from_client=some-client-id' \
--data-urlencode 'timestamp=123' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/messages/{message_id}

注意,该接口仅删除服务端的消息,对客户端无影响。

参数约束说明
from_client必填消息的发件人 client ID
timestamp必填消息的时间戳

返回:

{}

增加临时性禁言用户

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_id": "some-client-id", "ttl": 50}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/temporary-silenceds
参数说明
client_id要禁言的 Client ID,字符串
ttl禁言的时间,秒数,最长 24 小时

返回

{}

移除临时性禁言用户

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'client_id=some-client-id' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/temporary-silenceds

返回

{}

对话权限

该功能介绍可参考即时通讯开发指南第三篇中的《权限管理与黑名单》一节。

增加权限

该接口要求使用 master key。 每个对话最多允许添加 500 个永久性禁言用户。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"clientId": "client", "role": "role"}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/member-infos
参数说明
clientId用户 ID,字符串
role角色,可选值 Member、Manager、Owner

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

删除权限

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/conversations/{conv_id}/member-infos/{info-id}
参数说明
info-id该记录对应的 objectId

返回

{}

更新权限

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"clientId": "client", "role": "role"}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/member-infos/{info-id}
参数说明
clientId用户 ID,字符串
role角色,可选值 Member、Manager、Owner。可选
info-id该记录对应的 objectId

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

查询权限

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'skip=1' \
--data-urlencode 'limit=20' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/member-infos
参数说明
skip
limit与 skip 联合使用实现分页
role本次查询只希望包含该角色

返回

{"results": [{"clientId":"client1", "objectId":"5a5d7433c3422b31ed845e76", "role": "Manager"}]}

增加永久性禁言用户

该接口要求使用 master key。 每个对话最多允许添加 500 个永久性禁言用户。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/permanent-silenceds
参数说明
client_ids要禁言的 Client ID 列表,数组

返回

{}

移除永久性禁言用户

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/permanent-silenceds

返回

{}

查询永久性禁言列表

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'limit=20' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/permanent-silenceds
参数约束说明
limit可选与 next 联合使用实现分页,默认 10
next可选第一次查询时返回,后面的查询带着这个参数,实现分页查询

返回

{"client_ids": ["client1", "client2"]}

黑名单

该功能介绍可参考即时通讯开发指南第三篇中的《权限管理与黑名单》一节。

增加对话黑名单

该接口要求使用 master key。

加入黑名单的 client 不允许再加入该对话,如果之前在该对话中将被移除。每个对话最多允许添加 500 个黑名单。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/blacklists
参数说明
client_ids要拉黑的 Client ID 列表,数组

返回

{}

移除对话黑名单

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/blacklists

返回

{}

查询对话黑名单

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/conversations/{conv_id}/blacklists
参数约束说明
limit可选与 next 联合使用实现分页,默认 10
next可选第一次查询时返回,后面的查询带着这个参数,实现分页查询

返回

{"client_ids": ["client1", "client2"]}

聊天室

创建聊天室

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"name":"My First Chatroom"}' \
https://{{host}}/1.2/rtm/chatrooms

对话的字段可参考即时通讯总览的《对话》一节。

返回

{"objectId":"5a5d7432c3422b31ed845e75", "createdAt":"2018-01-16T03:40:32.814Z"}

查询聊天室

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'where={"name": "chatroom"}' \
--data-urlencode 'skip=1' \
--data-urlencode 'limit=20' \
https://{{host}}/1.2/rtm/chatrooms
参数约束说明
skip可选
limit可选与 skip 联合使用实现分页
where可选请参考数据存储 REST API 使用详解的《查询》一节。

返回

{"results":[
{"name":"My First Chatroom",
"createdAt":"2018-01-17T04:15:33.386Z", "updatedAt":"2018-01-17T04:15:33.386Z",
"objectId"=>"5a5ecde6c3422b738c8779d7"}
]}

更新聊天室

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"name":"Updated Chatroom"}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

删除聊天室

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}

返回

{}

随机获取在线成员

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/members

返回

{"result": ["clientid1", "clientid2", "clientid3"]}

查询在线成员数

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/members/online-count

返回

{"result": 3}

聊天室-发消息

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": ""}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages

注意,由于这个接口的管理性质,当你通过这个接口发送消息时,我们不会检查 from_client 是否有权限给这个聊天室发送消息,而是统统放行,请谨慎使用这个接口。 如果你在应用中使用了我们内部定义的富媒体消息格式,在发送消息时 message 字段需要相应的格式要求。 此外,聊天室目前不支持将消息同步发送给在线的 from_client

参数约束说明
from_client必填消息的发件人 client Id
message必填消息内容(这里的消息内容的本质是字符串,但是我们对字符串内部的格式没有做限定,理论上开发者可以随意发送任意格式,只要大小不超过 5 KB 限制即可。)
transient可选是否为暂态消息,默认 false
priority可选定义消息优先级,可选值为 high、normal、low,分别对应高、中、低三种优先级。该参数大小写不敏感,默认为中优先级 normal。本参数仅对暂态消息或聊天室的消息有效,高优先级下在服务端与用户设备的连接拥塞时依然排队。
mention_all可选布尔类型,用于提醒对话内所有成员注意本消息。
mention_client_ids可选数组类型,表示需要提醒注意本消息的对话内成员 client_id 列表,最多能包含 20 个 client Id。

返回说明:

默认情况下发送消息 API 使用异步的方式,调用后返回消息 id 和接收消息的服务器时间戳,例如 {"msg-id":"qNkRkFWOeSqP65S9fDyHJw", "timestamp":1495431811151}

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

查询历史消息

该接口要求使用 master key。 为了保证获取聊天记录的安全性,可以开启签名认证,具体可以参考即时通讯开发指南第三篇的《安全与签名》一节。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/messages
参数约束说明
msgid可选起始的消息 id,使用时必须加上对应消息的时间戳 timestamp 参数,作为查询的起点
timestamp可选查询起始的时间戳。默认是当前时间,单位是毫秒
till_msgid可选查询终止的消息 id。使用时必须加上消息的时间戳 till_timestamp 参数,作为查询的终点
till_timestamp可选查询终止的时间戳,默认为 0,单位是毫秒
include_start可选是否包含由 timestamp 与 msgid 确定的起始消息。布尔值,默认为 false
include_stop可选是否包含由 till_timestamp 与 till_msgid 确定的终止消息。布尔值,默认为 false
reversed可选以默认排序(默认按时间降序)相反的方向返回结果,这时 till_timestamp 默认为当前时间戳,timestamp 默认为 0。布尔值,默认为 false
limit可选返回条数限制,可选,默认 100 条,最大 1000 条
client_id可选查看者 id(签名参数)
nonce可选签名随机字符串(签名参数)
signature_ts可选签名时间戳(签名参数),单位是毫秒
signature可选签名(签名参数)

本接口时间参数较多,这里举一示例供大家参考。比如某对话内有三条消息,id 分别为 id1、id2、id3,发消息的时间分别是 t1、t2、t3(t1 < t2 < t3),下面列举出不同参数组合的查询结果(空白表示使用默认值):

timestampmsgidtill_timestamptill_msgidinclude_startinclude_stopreversed结果
t3id3t1id1id2
t3id3t1id1trueid3 id2
t3id3t1id1trueid2 id1
t1id1t3id3trueid2
t1id1t3id3truetrueid1 id2
t1id1t3id3truetrueid2 id3

返回数据格式,JSON 数组,默认按消息记录从新到旧排序,设置请求参数 reversed 后以相反的方向排序。

返回:

[
{
"timestamp": 1408008498571,
"conv-id": "219946ef32e40c515d33ae6975a5c593",
"data": "今天天气不错!",
"from": "u111872755_9d0461adf9c267ae263b3742c60fa",
"msg-id": "vdkGm4dtRNmhQ5gqUTFBiA",
"is-conv": true,
"is-room": false,
"to": "5541c02ce4b0f83f4d44414e",
"bin": false,
"from-ip": "202.117.15.217"
},
...
]

如需查询某个用户发出的消息,可以调用 GET /rtm/clients/{client_id}/messages 这个接口。 如需查询整个应用的历史消息,可以调用 GET /rtm/messages 这个接口

聊天室-修改消息

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": "", "timestamp": 123}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages/{message_id}
参数约束说明
from_client必填消息的发件人 client ID
message必填消息体
timestamp必填消息的时间戳

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

聊天室-撤回消息

该接口要求使用 master key。需要相应 SDK 的支持,具体可参考上面的「修改消息」接口。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "timestamp": 123}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages/{message_id}/recall
参数约束说明
from_client必填消息的发件人 client ID
timestamp必填消息的时间戳

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

删除消息

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'from_client=some-client-id' \
--data-urlencode 'timestamp=123' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages/{message_id}

注意,该接口仅删除服务端的消息,对客户端无影响。

参数约束说明
from_client必填消息的发件人 client ID
timestamp必填消息的时间戳

返回:

{}

增加临时性禁言用户

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_id": "some-client-id", "ttl": 50}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/temporary-silenceds
参数说明
client_id要禁言的 id,字符串
ttl禁言的时间,秒数,最长 24 小时

返回

{}

移除临时性禁言用户

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'client_id=some-client-id' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/temporary-silenceds

返回

{}

对话权限

该功能介绍可参考即时通讯开发指南第三篇中的《权限管理与黑名单》一节。

增加权限

该接口要求使用 master key。 每个聊天室最多允许添加 10,000 个永久性禁言用户。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"clientId": "client", "role": "role"}' \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos
参数说明
clientId用户 ID,字符串
role角色,可选值 Member、Manager、Owner

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

删除权限

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos/{info-id}
参数说明
info-id该记录对应的 objectId

返回

{}

更新权限

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"clientId": "client", "role": "role"}' \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos/{info-id}
参数说明
client_id要禁言的 id,字符串。可选
role角色,可选值 Member、Manager、Owner。可选
info-id该记录对应的 objectId

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

查询权限

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'skip=1' \
--data-urlencode 'limit=20' \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos
参数说明
skip
limit与 skip 联合使用实现分页
role本次查询只希望包含该角色

返回

{"results": [{"clientId":"client1", "objectId":"5a5d7433c3422b31ed845e76", "role": "Manager"}]}

增加永久性禁言用户

该接口要求使用 master key。 每个聊天室最多允许添加 500 个永久性禁言用户。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/permanent-silenceds
参数说明
client_ids要禁言的 Client ID 列表,数组

返回

{}

移除永久性禁言用户

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/permanent-silenceds

返回

{}

查询永久性禁言列表

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'limit=20' \
https://{{host}}/1.2/rtm/chatrooms/{conv_id}/permanent-silenceds
参数约束说明
limit可选与 next 联合使用实现分页,默认 10
next可选第一次查询时返回,后面的查询带着这个参数,实现分页查询

返回

{"client_ids": ["client1", "client2"]}

黑名单

该功能介绍可参考即时通讯开发指南第三篇中的《权限管理与黑名单》一节。

增加聊天室黑名单

该接口要求使用 master key。

加入黑名单的 client 不允许再加入该聊天室,如果之前在该聊天室中将被移除。每个聊天室最多允许添加 10,000 个黑名单。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/blacklists
参数说明
client_ids要拉黑的 Client ID 列表,数组

返回

{}

移除聊天室黑名单

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/blacklists

返回

{}

查询聊天室黑名单

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/blacklists
参数约束说明
limit可选与 next 联合使用实现分页,默认 10
next可选第一次查询时返回,后面的查询带着这个参数,实现分页查询

返回

{"client_ids": ["client1", "client2"]}

服务号

创建服务号

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"name":"My First Service-conversation"}' \
https://{{host}}/1.2/rtm/service-conversations

对话的字段可参考即时通讯总览的《对话》一节。

返回

{"objectId":"5a5d7432c3422b31ed845e75", "createdAt":"2018-01-16T03:40:32.814Z"}

查询服务号

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'where={"name": "service"}' \
--data-urlencode 'skip=1' \
--data-urlencode 'limit=20' \
https://{{host}}/1.2/rtm/service-conversations
参数约束说明
skip可选
limit可选与 skip 联合使用实现分页
where可选请参考数据存储 REST API 使用详解的《查询》一节。

返回

{"results":[
{"name":"My First Service-conversation",
"createdAt":"2018-01-17T04:15:33.386Z",
"updatedAt":"2018-01-17T04:15:33.386Z",
"objectId":"5a5ecde6c3422b738c8779d7"}
]}

更新服务号

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"name":"Updated Service-conversation"}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}

返回

{"updatedAt":"2018-01-16T03:40:37.683Z", "objectId":"5a5d7433c3422b31ed845e76"}

删除服务号

_Conversation 表默认 ACL 权限下本接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}

返回

{}

订阅服务号

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_id":"client_id"}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers

返回

{}

取消订阅

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/{client_id}

返回

{}

遍历查询订阅者

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers
参数约束说明
limit可选返回条数限制,默认是 50 条,最大 50 条。
client_id可选查询起始订阅者 client id,不填则从订阅者列表起始位置开始遍历。查询结果不会再包含当前指定的订阅者 client id。

返回

[{"timestamp":1491467841116,"subscriber":"client id 1","conv_id":"55b871"},
{"timestamp":1491467852768,"subscriber":"client id 2","conv_id":"55b872"}, ...]

其中 timestamp 表示用户订阅系统对话的时间,subscriber 是订阅用户的 client id。如果一次没有获取完,需要从结果列表中取最后一个订阅者的 client id,作为 client_id 参数再次调用本接口以获取下一批订阅者列表。

查询订阅者数

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/count

返回

{"count": 100}

给所有订阅者发消息

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": ""}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/broadcasts
参数约束说明
from_client必选消息的发件人 client ID
message必选消息体
push可选附带的推送内容,如果设置,所有 iOS 和 Android 用户会收到这条推送通知。字符串或 JSON 对象

返回:

{"msg-id":"qNkRkFWOeSqP65S9fDyHJw", "timestamp":1495431811151}

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

修改给所有订阅者发送的消息

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": "", "timestamp": 123}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}
参数约束说明
from_client必填消息的发件人 client ID
message必填消息体
timestamp必填消息的时间戳

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

撤回给所有订阅者发送的消息

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "timestamp": 123}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}/recall
参数约束说明
from_client必填消息的发件人 client ID
timestamp必填消息的时间戳

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

给任意用户单独发消息

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": ""}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages

注意,由于这个接口的管理性质,当你通过这个接口发送消息时,我们不会检查 from_client 是否有权限给这个服务号发送消息,而是统统放行,请谨慎使用这个接口。 如果你在应用中使用了我们内部定义的富媒体消息格式,在发送消息时 message 字段需要遵守相应的格式要求。

参数约束说明
from_client必填消息的发件人 client Id
to_clients必填数组类型,表示接收消息的 client Id 列表,最多能包含 20 个 client Id
message必填消息内容(这里的消息内容的本质是字符串,但是我们对字符串内部的格式没有做限定,
理论上开发者可以随意发送任意格式,只要大小不超过 5 KB 限制即可。)
transient可选是否为暂态消息,默认 false
no_sync可选默认情况下消息会被同步给在线的 from_client 用户的客户端,设置为 true 禁用此功能。
push_data可选以消息附件方式设置本条消息的离线推送通知内容。如果目标接收者使用的是 iOS 设备并且当前不在线,我们会按照该参数填写的内容来发离线推送。请参看即时通讯开发指南第三篇的《离线推送通知》一节。
priority可选定义消息优先级,可选值为 high、normal、low,分别对应高、中、低三种优先级。该参数大小写不敏感,默认为中优先级 normal。本参数仅对暂态消息或聊天室的消息有效,高优先级下在服务端与用户设备的连接拥塞时依然排队。

返回说明:

默认情况下发送消息 API 使用异步的方式,调用后返回消息 id 和接收消息的服务器时间戳,例如 {"msg-id":"qNkRkFWOeSqP65S9fDyHJw", "timestamp":1495431811151}

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

修改给用户单独发送的消息

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": "", "timestamp": 123, "to_clients":["a","b","c"]}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}
参数约束说明
from_client必填消息的发件人 client ID
message必填消息体
timestamp必填消息的时间戳
to_clients必填数组类型,表示接收目标消息的 client Id 列表,最多能包含 20 个 client Id

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

撤回给用户单独发送的消息

该接口要求使用 master key。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "timestamp": 123, "to_clients":["a","b","c"]}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}/recall
参数约束说明
from_client必填消息的发件人 client ID
timestamp必填消息的时间戳
to_clients必填数组类型,表示接收目标消息的 client Id 列表,最多能包含 20 个 client Id

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

删除给用户单独发送的消息

本接口要求使用 master key,并且只能删除订阅消息或给用户单独发送的消息,无法删除广播消息。 广播消息请调用 DELETE /1.2/rtm/broadcasts/{message_id} 接口删除。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'from_client=some-client-id' \
--data-urlencode 'timestamp=123' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/{client_id}/messages/{message_id}

注意,该接口仅删除服务端的消息,对客户端无影响。

参数约束说明
from_client必填消息的发件人 client ID
timestamp必填消息的时间戳

返回:

{}

查询服务号给某用户发的消息

该接口要求使用 master key。查询结果包含服务号发送的订阅广播消息也包含单独发送的消息。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/{client_id}/messages

参数和返回值与查询历史消息接口相同。

黑名单

该功能介绍可参考即时通讯开发指南第三篇中的《权限管理与黑名单》一节。

增加服务号黑名单

该接口要求使用 master key。

加入黑名单的 client 不允许再加入该服务号,如果之前在该服务号中将被移除。每个服务号最多允许添加 10,000 个黑名单。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/blacklists
参数说明
client_ids要拉黑的 Client ID 列表,数组

返回

{}

移除服务号黑名单

该接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/blacklists

返回

{}

查询服务号黑名单

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-d '{"client_ids": ["client1", "client2"]}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/blacklists
参数约束说明
limit可选与 next 联合使用实现分页,默认 10
next可选第一次查询时返回,后面的查询带着这个参数,实现分页查询

返回

{"client_ids": ["client1", "client2"]}

用户

查询在线成员

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"client_ids": ["Tom", "Jerry"]}' \
https://{{host}}/1.2/rtm/clients/check-online
参数约束说明
client_ids必选要查询的 client ID 列表,最多 20 个

返回在线的 ID 列表

{"results":["client1"]}

注意,该接口不判断用户是否存在,「用户不存在」视同「用户不在线」。

查询未读消息数

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-G \
--data-urlencode 'conv_id=...' \
https://{{host}}/1.2/rtm/clients/{client_id}/unread-count
参数约束说明
conv_id可选对话 ID,若不传此参数,查询 client 在所有对话中的未读消息数

返回

{"count":1}

强制下线

该接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"reason": "why"}' \
https://{{host}}/1.2/rtm/clients/{client_id}/kick
参数约束说明
reason可选下线原因,字符串,不超过 20 个字符

返回

{}

查询订阅的服务号

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-G \
--data-urlencode 'conv_id=...' \
--data-urlencode 'timestamp=...' \
--data-urlencode 'limit=...' \
--data-urlencode 'direction=...' \
https://{{host}}/1.2/rtm/clients/{client_id}/service-conversations
参数约束类型说明
conv_id可选字符串查询起始服务号 id,不填则从订阅列表起始位置开始遍历。查询结果不会再包含本对话
timestamp可选数字查询起始对话被订阅时间。虽然是可选字段但当提供 conv_id 时本字段必填,值必须为订阅 conv_id 参数所指定系统对话的时间,单位是毫秒
limit可选数字返回条数限制,默认是 50 条
direction可选字符串查询结果按时间排序方式,old 表示降序,new 表示升序,默认是 new。使用 old 则先返回最近订阅的对话,使用 new 则先返回最早订阅的对话

返回目标用户订阅系统对话的列表:

[{"timestamp":1482994126561,"subscriber":"XXX","conv_id":"convId1"},
{"timestamp":1491467945277,"subscriber":"XXX","conv_id":"convId2"}, ...]

其中 timestamp 表示用户订阅系统对话的时间,subscriber 是订阅用户的 client id。如果一次没有获取完,需要从结果列表中取最后一个服务号 ID 和订阅时间,分别作为 conv_id 和 timestamp 参数再次调用本接口以获取下一批订阅的系统对话。

查询用户发送消息

该接口要求使用 master key。 使用这个接口可以查询某 client_id 在单聊、群聊与聊天室里发的消息。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/clients/{client_id}/messages

参数与返回值可以参考 GET /1.2/rtm/conversations/{conv_id}/messages 接口。

增加黑名单

该接口要求使用 master key。 一个 client 可以把一个 群聊/聊天室/服务号 加入黑名单,这样其他人就无法要求其加入该对话了。 目前不支持 client 把另一个 client 加入黑名单。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"conv_id": ""}' \
https://{{host}}/1.2/rtm/clients/{client_id}/blacklists
参数约束说明
conv_id必选拉黑的 群聊/聊天室/服务号 ID

返回

{}

移除黑名单

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"conv_id": ""}' \
https://{{host}}/1.2/rtm/clients/{client_id}/blacklists

返回

{}

查询黑名单

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/clients/{client_id}/blacklists
参数约束说明
limit可选与 next 联合使用实现分页,默认 10
next可选第一次查询时返回,后面的查询带着这个参数,实现分页查询

返回

{"conv_ids":["conv1"], "next":"1"}

获取登录签名

本接口可以让使用了 LCUser 的应用方便快捷地实现登录认证。 登录认证默认关闭,可以进入 云服务控制台 > 消息 > 即时通讯 > 设置 > 即时通讯选项,勾选 登录启用签名认证 进行开启。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-G \
--data-urlencode 'session_token=some-token' \
https://{{host}}/1.2/rtm/clients/sign
参数约束说明
session_token必选LCUser 的 sessionToken

返回

{
"signature":"bc884dbb617aab1efc228229210e487330abfc7d",
"nonce":"akywke3f28",
"client_id":"5fb4ff18d0deed36ea501c8a",
"timestamp":1614237989966
}

注意,虽然这是一个 GET 请求,但并不是幂等的,每次调用返回的签名都不相同。

为了方便用户进行细粒度控制,实现自定义功能(如黑名单),本接口提供了一个 hook _rtmClientSign,在验证 sessionToken 后去调用,传入的参数为 LCUser 构成的 JSON 对象:

{
"email": "",
"sessionToken": "",
"updatedAt": "", // 格式:2017-07-11T07:58:10.149Z
"phone": "",
"objectId": "",
"username": "",
"createdAt": "", // 格式:2017-07-11T07:58:10.149Z
"emailVerified": true/false,
"mobilePhoneVerified": true/false
}

可以返回两类结果:

{"result": true} // 允许签名
{"result": false, "error": "error message"} // 拒绝签名

全局 API

查询用户数

本接口会返回应用当前在线用户总数,以及当天有登录记录的独立用户总数。本接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/stats

返回

{"result":{"online_user_count":10212,"user_count_today":1002324}}

其中 online_user_count 表示当前应用在线用户总数,user_count_today 表示当天有登录记录的独立用户总数。

查询所有对话

本接口会返回所有的 单聊群聊/聊天室/服务号。在 _Conversation 表默认 ACL 权限下要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/all-conversations
参数约束说明
skip可选
limit可选与 skip 联合使用实现分页
where可选参考《存储 REST API 指南》中的《查询》一节

返回

{"results":[
{"name":"conversation",
"createdAt":"2018-01-17T04:15:33.386Z", "updatedAt":"2018-01-17T04:15:33.386Z",
"objectId":"5a5ecde6c3422b738c8779d7"}
]}

全局广播

该接口可以给该应用所有 client 广播一条消息,每天最多 30 条。本接口要求使用 master key。

curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "1a", "message": "{\"_lctype\":-1,\"_lctext\":\"这是一个纯文本消息\",\"_lcattrs\":{\"a\":\"_lcattrs 是用来存储用户自定义的一些键值对\"}}", "conv_id": "..."}' \
https://{{host}}/1.2/rtm/broadcasts
参数约束类型说明
from_client必填字符串消息的发件人 id
conv_id必填字符串发送到对话 id,仅限于服务号
message必填字符串消息内容(这里的消息内容的本质是字符串,但是我们对字符串内部的格式没有做限定,理论上开发者可以随意发送任意格式,只要大小不超过 5 KB 限制即可。)
valid_till可选数字过期时间,UTC 时间戳(毫秒),最长为 1 个月之后。默认值为 1 个月后。
push可选字符串或 JSON 对象附带的推送内容,如果设置,所有 iOS 和 Android 用户会收到这条推送通知。
transient可选布尔值默认为 false。该字段用于表示广播消息是否为暂态消息,暂态消息只会被当前在线的用户收到,不在线的用户再次上线后也收不到该消息。

Push 的格式与《推送 REST API 指南》的《消息内容 Data》一节中 data 下面的部分一致。如果您需要指定开发证书推送,需要在 push 的 json 中设置 "_profile": "dev",例如:

{
"alert": "消息内容",
"category": "通知分类名称",
"badge": "Increment",
"_profile": "dev"
}

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

修改广播消息

该接口要求使用 master key。

广播消息修改仅对当前还未收到该广播消息的设备生效,如果目标设备已经收到了该广播消息则无法修改。请慎重发送广播消息。

curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
-H "Content-Type: application/json" \
-d '{"from_client": "", "message": "", "timestamp": 123}' \
https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}
参数约束说明
from_client必填消息的发件人 client ID
message必填消息体
timestamp必填消息的时间戳

成功则返回状态码 200 OK

频率限制:

此接口受频率限制,详见后文接口请求频率限制一节。

删除广播消息

调用此 API 将删除已发布的广播消息,仅对还未收到广播消息的设备生效,已收到广播消息的设备无法删除消息。本接口要求使用 master key。

curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/broadcasts/{message_id}
参数约束说明
message_id必填要删除的消息 id,字符串

成功则返回状态码 200 OK

查询广播消息

调用此 API 可查询目前有效的广播消息。本接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/broadcasts?conv_id={conv_id}
参数约束说明
conv_id必填服务号 id
limit可选返回消息条数
skip可选跳过消息条数,用于翻页

查询应用内所有历史消息

该接口要求使用 master key。

curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.2/rtm/messages

参数与返回值可以参考 GET /1.2/rtm/conversations/{conv_id}/messages 接口。

接口请求频率限制

本文档中和消息操作有关的 REST API 有请求频率以及总量的限制(即时通讯客户端 SDK 的 API 不受此限制影响),具体如下:

普通消息

1.1 版本:

  • 发送消息、系统对话给用户发消息(/1.1/rtm/messages
  • 修改与撤回消息 (/1.1/rtm/patch/message)

1.2 版本:

限制

商用版(每应用)开发版(每应用)
最大 9000 次/分钟,默认 1800 次/分钟120 次/分钟

所有接口共享额度。超过额度限制后一分钟内 LeanCloud 会拒绝请求持续返回 429 错误码,一分钟后会重新处理请求。

商用版应用的上限可以在 云服务控制台 > 消息 > 即时通讯 > 设置 > 服务阈值 > 普通消息 API 调用频率上限 修改。 按照每日调用频率峰值实行阶梯收费,如下表所示:

每分钟调用频率费用
0 ~ 1800免费
1801 ~ 3600¥20 元 / 天
3601 ~ 5400¥30 元 / 天
5401 ~ 7200¥40 元 / 天
7201 ~ 9000¥50 元 / 天

国际版

每分钟调用频率费用
0 ~ 1800免费
1801 ~ 3600$6 USD / 天
3601 ~ 5400$9 USD / 天
5401 ~ 7200$12 USD / 天
7201 ~ 9000$15 USD / 天

每日调用频率峰值可以在 控制台 > 消息 > 即时通讯 > 统计 > API 请求频率峰值 中查看。

订阅消息

1.1 版本:

  • 系统对话发送订阅消息 (/1.1/rtm/broadcast/subscriber

1.2 版本:

限制

限制商用版开发版
频率限制每应用 30 次/分钟每应用 10 次/分钟
总量限制全天最多 1000 次全天最多 100 次

所有接口共享额度。超过频率限制后 1 分钟内云端会拒绝请求持续返回 429 错误码,一分钟后会重新处理请求;超过总量限制后当天会拒绝之后的所有请求并返回 429 错误码。

广播消息

1.1 版本:

  • 发送广播消息 (/1.1/rtm/broadcast

1.2 版本:

限制

限制商用版开发版
频率限制每应用 10 次/分钟每应用 1 次/分钟
总量限制全天最多 30 次全天最多 10 次

所有接口共享以上额度。超过频率限制后 1 分钟内云端会拒绝请求持续返回 429 错误码,一分钟后会重新处理请求;超过总量限制后当天会拒绝之后的所有请求并返回 429 错误码。