Skip to main content

Reaction

During one-to-one chats and group chats, users can reply a specified message with emojis, which adds fun and diversity to real-time chatting. In Chat, this feature is known as reaction. This page shows how to use the Chat RESTful APIs to implement reaction in your project.

Before calling the following methods, make sure you understand the call frequency limit of the Chat RESTful APIs as described in Limitations.

Common parameters

The following table lists common request and response parameters of the Chat RESTful APIs:

Request parameters

ParameterTypeDescriptionRequired
hostStringThe domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see Get the information of your project.Yes
org_nameStringThe unique identifier assigned to each company (organization) by the Chat service. For how to get the org name, see Get the information of the Chat project.Yes
app_nameStringThe unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of the Chat project.Yes
usernameStringThe unique login account of the user. The user ID must be 64 characters or less and cannot be empty. The following character sets are supported:
  • 26 lowercase English letters (a-z)
  • 26 uppercase English letters (A-Z)
  • 10 numbers (0-9)
  • "_", "-", "."
  • The username is case insensitive, so Aa and aa are the same username.
  • Ensure that each username under the same app is unique.
  • Do not set this parameter as a UUID, email address, phone number, or other sensitive information.
Yes

Response parameters

ParameterTypeDescription
dataJSONThe response details.
timestampNumberThe Unix timestamp (ms) of the HTTP response.
usernameStringThe user ID.
groupnameStringThe chat group name.

Authorization

Chat RESTful APIs require Bearer HTTP authentication. Every time an HTTP request is sent, the following Authorization field must be filled in the request header:


_1
Authorization: Bearer ${YourAppToken}

In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Chat RESTful APIs only support authenticating users using app tokens. For details, see Authentication using App Token.

Create/Add a reaction

This method creates or adds a reaction to a specified message in one-to-one chats or group chats.

HTTP request


_1
POST https://{host}/{org_name}/{app_name}/reaction/user/{userId}

Path parameter

For the path parameters and the detailed descriptions, see Common parameters.

Request header

ParameterTypeDescriptionRequired
Content-TypeStringapplication/x-www-form-urlencodedYes
AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

Request body

ParameterTypeDescription
msg_IdStringThe message ID to which you want to add the reaction.
messageStringThe ID of the emoji, same as that on the client. The maximum length is 128 bytes.

HTTP Response

Response body

If the returned HTTP status code is 200, the request succeeds, and the data in the response contains the following fields:

ParameterTypeDescription
requestStatusCodeStringThe status code of this request. ok means that the request succeeds.
idStringThe reaction ID.
msgIdStringThe message ID.
msgTypeStringThe message type:
  • chat: One-to-one chat.
  • groupchat: Group chat.
groupIdStringThe chat group ID. If the message type is chat, the server returns null.
reactionStringThe ID of the emoji added as the reaction, same as message in the request body.
createAtInstantThe time when the reaction is created.
updateAtInstantThe time when the reaction is updated.

For other fields and the detailed descriptions, see Public parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example


_4
curl -g -X POST 'http://XXXX/XXXX/XXXX/reaction/user/e1' -H 'Authorization: Bearer {YourAppToken}' -H 'Content-Type: application/json' --data-raw '{
_4
"msgId":"997625372793113144",
_4
"message":"emoji_40"
_4
}'

Response example


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

Retrieve reactions with message IDs

This method retrieves the information of the reaction according to the message ID, including the reaction ID, emoji ID, and the user IDs that have used this reaction. This method only returns the first three chat users that added this reaction.

For each method call, you can retrieve reactions in either one-to-one chats or group chats, but not in both of them.

HTTP request


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

Path parameter

For the path parameters and the detailed descriptions, see Common parameters.

Query parameter

ParameterTypeDescriptionRequired
msgIdListArrayThe ID of the message from which you attempt to retrieve reactions.Yes
msgTypeStringThe chat type:
  • chat: One-to-one chats.
  • groupchat: Group chats.
Yes
groupIdStringThe ID of the chat group. This parameter is only required if you set msgType to groupchat.No

Request header

ParameterTypeDescriptionRequired
Content-TypeStringapplication/x-www-form-urlencodedYes
AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the data in the response contains the following fields:

ParameterTypeDescription
requestStatusCodeStringThe status code of this request. ok means that the request succeeds.
msgIdStringThe message ID.
reactionIdStringThe reaction ID returned in the response body of Create a reaction.
reactionStringThe emoji ID that is the same as the message parameter specified in the request body when adding a reaction.
countNumberThe number of users that have added this reaction to the message.
stateBoolWhether the user sending this request has added a reaction to this message:
  • true: Yes.
  • false: No.
userListArrayThe list of user IDs that have added this reaction. It contains a maximum of three users that first added this reaction.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example


_1
curl -g -X GET 'http://XXXX/XXXX/XXXX/reaction/user/{{userId}}?msgIdList=msgId1&msgType=chat' -H 'Authorization: Bearer {YourAppToken}'

Response example


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

Delete a reaction

This method deletes a reaction.

HTTP request


_1
DELETE https://{host}/{org_name}/{app_name}/reaction/user/{userId}

Path parameter

For the parameters and the detailed descriptions, see Common parameters.

Reqest header

ParameterTypeDescriptionRequired
Content-TypeStringapplication/x-www-form-urlencodedYes
AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

Query parameters

ParameterTypeDescriptionRequired
msgIdStringThe message ID.Yes
messageStringThe ID of the emoji that is added as the reaction.Yes

HTTP Response

Response body

If the returned HTTP status code is 200, the request succeeds, and the data in the response contains the following fields:

ParameterTypeDescription
requestStatusCodeStringThe status code of this request. ok means that the request succeeds.
timestampLongThe Unix timestamp of this response, in milliseconds.

For other fields and the detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example


_1
curl -g -X DELETE 'http://XXXX/XXXX/XXXX/reaction/user/wz?msgId=997625372793113144&message=emoji_40' -H 'Authorization: Bearer {YourAppToken}'

Response example


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

Retrieve the detailed information of the reaction

This method retrieves the detailed information of the reaction by specifying the message ID and reaction ID.

HTTP request


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

Path parameter

For the parameters and the detailed description, see Common parameters.

Query parameter

ParameterTypeDescriptionRequired
msgIdStringThe message ID.Yes
messageStringThe ID of the emoji that is added as the reaction.Yes
limitNumberThe number of reactions retrieved on each page when you retrieve the reactions with pagination. The value range is [1,100]. The default value is 100.No
cursorStringThe starting page from which to retrieve data if you retrieve the reactions with pagination.No

Request header

ParameterTypeDescriptionRequired
Content-TypeStringapplication/x-www-form-urlencodedYes
AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes
### HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the data in the response contains the following fields:

ParameterTypeDescription
requestStatusCodeStringThe status code of this request. ok means that the request succeeds.
reactionIdStringThe reaction ID.
reactionStringThe emoji ID that is the same as the message parameter specified in the request body when adding a reaction.
countNumberThe number of users that have added the reaction.
stateBoolWhether the user sending this request has added a reaction to this message:
  • true: Yes.
  • false: No.
userListArrayThe list of the users that have added this reaction. Note that this list only contains the last three user IDs to do so.
cursorStringThe cursor that indicates that starting position of the next query.

For other fields and the detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example


_5
// Starts querying from the first page
_5
curl -g -X GET 'http://XXXX/XXXX/XXXX/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&limit=50' -H 'Authorization: Bearer {YourAppToken}'
_5
_5
// Starts querying from the second page
_5
curl -g -X GET 'http://XXXX/XXXX/XXXX/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&cursor=944330529971449164&limit=50' -H 'Authorization: Authorization: Bearer {YourAppToken}'

Response example


_14
{
_14
"requestStatusCode": "ok",
_14
"timestamp": 1645776986146,
_14
"data": {
_14
"reactionId": "946463470818405943",
_14
"reaction": "message123456",
_14
"userCount": 1,
_14
"state": true,
_14
"userList": [
_14
"wz1"
_14
],
_14
"cursor": "946463471296555192"
_14
}
_14
}

Status codes

For details, see HTTP Status Codes.