消息表情回复 Reaction REST API

大约 8 分钟

消息表情回复 Reaction REST API

消息表情回复(“Reaction”)指用户在单聊和群聊场景中对单条消息回复表情,可丰富用户聊天时的互动方式。对于单个消息,一个消息表情即为一个 Reaction,若不同用户重复添加同一消息表情,Reaction 数量计为 1。每条消息默认可添加 20 个 Reaction。

本页介绍如何使用即时通讯 IM RESTful API 实现 Reaction 功能。

前提条件

要调用环信即时通讯 RESTful API,请确保满足以下要求:

公共参数

请求参数

参数类型是否必需描述
hostString访问 RESTful API 的域名或服务器信息。
-公有云集成为 环信即时通讯控制台的 即时通讯->服务概览页面下的 域名配置- Rest Api
-私有化集成为部署后 服务器地址:端口
org_nameString每个公司(组织)分配的唯一标识。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Orgname
app_nameString创建应用时填入的应用名称。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Appname
usernameString用户 ID。

认证方式

环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,必须在请求头部填入如下 Authorization 字段:

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 仅支持使用 app token 的鉴权方式,详见 使用 App Token 鉴权

创建/追加 Reaction

在单聊或群聊场景中对单条消息创建或追加 Reaction。

创建 Reaction 指对消息添加第一条 Reaction,后续的 Reaction 添加称为追加。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/reaction/user/{username}

路径参数

参数及描述详见 公共参数

请求 header

参数类型是否必需描述
Content-TypeString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需
描述
msgIdString消息 ID。
messageString表情 ID。长度不能超过 128 个字符,必须与客户端的设置一致。该参数对支持的字符集类型没有限制,若使用特殊字符,获取和删除 Reaction 时需对特殊字符进行 URL 编码。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
requestStatusCodeString操作结果,ok 表示成功创建或追加 Reaction。
timestampLong请求响应的时间,Unix 时间戳,单位为毫秒。
dataJSON添加的 Reaction 的详情。
data.idStringReaction ID。
data.msgIdString添加 Reaction 的消息 ID。
data.msgTypeString消息的会话类型:
- chat:单聊;
- groupchat:群聊。
data.groupIdString群组 ID。该参数在单聊时为 null。
data.reactionString表情 ID,与客户端一致,与创建/追加 Reaction API的请求参数 message 相同。
data.createAtInstantReaction 的创建时间。
data.updateAtInstantReaction 的修改时间。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -g -X POST 'https://localhost:8089/easemob-demo/easeim/reaction/user/e1' -H 'Authorization: Bearer <YourAppToken>' -H 'Content-Type: application/json' --data-raw '{
    "msgId":"997625372793113144",
    "message":"emoji_40"
}'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1645774821181,
  "data": {
    "id": "946481033434607420",
    "msgId": "msg3333",
    "msgType": "chat",
    "groupId": null,
    "reaction": "emoji_40",
    "createdAt": "2022-02-24T10:57:43.138934Z",
    "updatedAt": "2022-02-24T10:57:43.138939Z"
  }
}

根据消息 ID 获取 Reaction

该方法根据单聊或群聊中的消息 ID 获取单个或多个消息的 Reaction 信息,包括 Reaction ID、使用的表情 ID、以及使用该 Reaction 的用户 ID 及用户人数。获取的 Reaction 的用户列表只展示最早三个添加 Reaction 的用户。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/reaction/user/{username}?msgIdList={N,M}&msgType={msgType}&groupId={groupId}

路径参数

参数及描述详见 公共参数

查询参数

参数类型是否必需描述
msgIdListArray需要查询的消息 ID 列表,最多可传 20 个消息 ID。
msgTypeString消息的会话类型:
- chat:单聊;
- groupchat:群聊。
groupIdString群组 ID。如果 msgType 设置为 groupchat,即拉取群中的 Reaction,必须指定群组 ID。

请求 header

参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
requestStatusCodeString接口相应 code 状态。OK 表示操作成功。
timestampLong请求响应的时间,Unix 时间戳,单位为毫秒。
dataJSON Array单个消息添加的 Reaction 的详情。
data.msgIdStringReaction 对应的消息 ID。
data.reactionListJSON Array单个消息的 Reaction 列表。
data.reactionList.reactionIdStringReaction ID。
data.reactionList.reactionString表情 ID,与客户端一致。该参数与创建/追加 Reaction API的请求参数 message 相同。
data.reactionList.countInt添加该 Reaction 的用户人数。
data.reactionList.stateBool当前请求用户是否添加过该 Reaction:
- true: 是;
- false:否。
data.reactionList.userListArray添加 Reaction 的用户 ID 列表。只返回最早操作 Reaction 的三个用户的 ID。

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -g -X GET 'https://localhost:8089/easemob-demo/easeim/reaction/user/{{userId}}?msgIdList=msgId1&msgType=chat' -H 'Authorization: Bearer <YourAppToken>'

响应示例

{
    "requestStatusCode": "ok",
    "timestamp": 1645774821181,
    "data": [
        {
            "msgId": "msg123",
            "reactionList": [
                {
                    "reactionId": "944330310986837168",
                    "reaction": "message123456",
                    "count": 3,
                    "state": false,
                    "userList": [
                        "test123",
                        "test456",
                        "test1"
                    ]
                }
            ]
        },
        {
            "msgId": "msg1234",
            "reactionList": [
                {
                    "reactionId": "945272584050659838",
                    "reaction": "message123456",
                    "count": 1,
                    "state": false,
                    "userList": [
                        "test5"
                    ]
                }
            ]
        }
    ]
}

删除 Reaction

删除当前用户追加的 Reaction。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/reaction/user/{username}?msgId={msgId}&message={message}

路径参数

参数及描述详见 公共参数

请求 header

参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

查询参数

参数类型是否必需描述
msgIdString消息 ID。
messageString表情 ID。长度不可超过 128 个字符。该参数的值必须与客户端一致。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
requestStatusCodeString操作结果。ok 表示成功删除 Reaction。
timestampLong请求响应的时间,Unix 时间戳,单位为毫秒。

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -g -X DELETE 'https://localhost:8089/easemob-demo/easeim/reaction/user/wz?msgId=997625372793113144&message=emoji_40' -H 'Authorization: Bearer <YourAppToken>'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1645774821181
}

根据消息 ID 和表情 ID 获取 Reaction 信息

该方法根据指定的消息的 ID 和表情 ID 获取对应的 Reaction 信息,包括使用了该 Reaction 的用户 ID 及用户人数。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/reaction/user/{username}/detail?msgId={msgId}&message={message}&limit={limit}&cursor={cursor}

路径参数

参数及描述详见 公共参数

查询参数

参数类型是否必需描述
msgIdString消息 ID。
messageString表情 ID。长度不可超过 128 个字符。该参数的值必须与客户端一致。
limitInt每页显示添加 Reaction 的用户数量。取值范围为 [1,50],默认值为 50
cursorString查询游标,指定数据查询的起始位置,分页获取时使用。

提示

分页获取时,服务器按用户 Reaction 添加时间的正序返回。若 limitcursor 均不传值,服务器返回最早添加 Reaction 的 50 个用户。

请求 header

参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
requestStatusCodeString操作结果,ok 表示成功获取 Reaction 信息。
timestampLong请求响应的时间,Unix 时间戳,单位为毫秒。
dataJSON消息添加的 Reaction 的详情。
data.reactionIdStringReaction ID。
data.reactionString表情 ID,与客户端一致。该参数与创建/追加 Reaction API的请求参数 message 相同。
data.countInt添加该 Reaction 的用户人数。
data.stateBool当前请求用户是否添加过该 Reaction。
- true:是;
- false:否。
data.userListArray按 Reaction 添加时间正序返回的用户 ID 列表。
data.cursorString查询游标,指定下次查询的起始位置。

其他字段及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例(第一页)

curl -g -X GET 'https://localhost:8089/easemob-demo/easeim/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&limit=50' -H 'Authorization: Bearer <YourAppToken>'

请求示例(第 N 页)

curl -g -X GET 'https://localhost:8089/easemob-demo/easeim/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&cursor=944330529971449164&limit=50' -H 'Authorization: Authorization: Bearer <YourAppToken>'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1645776986146,
  "data": {
    "reactionId": "946463470818405943",
    "reaction": "message123456",
    "count": 1,
    "state": true,
    "userList": ["wz1"],
    "cursor": "946463471296555192"
  }
}
上次编辑于: