# Reaction (/en/api-reference/api-ref/im/reaction)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
During one-to-one chats and group chats, users can reply to a message with emojis, which adds fun and diversity to real-time chatting. In Agora Chat, this feature is known as reaction. For a message, one emoji is counted as one reaction even if it is added repeatedly. A maximum of 20 reactions can be added for one message. To increase the upper limit, contact [support@agora.io](mailto\:support@agora.io).
This page shows how to use the Agora Chat RESTful API 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](./limitations#call-limit-of-server-sides).
## Common parameters [#common-parameters]
The following table lists common request and response parameters of the Chat RESTful APIs:
### Request parameters [#request-parameters]
| Parameter | Type | Description | Required |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `host` | String | The 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](/en/realtime-media/im/get-started/enable#get-the-information-of-the-agora-chat-project). | Yes |
| `app_id` | String | The unique identifier automatically assigned to each project by Agora | Yes |
| `username` | String | The 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)
* 10 numbers (0-9)
* "\_", "-", "."
Do not use any of the 26 uppercase English letters (A-Z). Ensure that each `username` under the same App ID is unique. Do not set this parameter as a [UUID](https://www.rfc-editor.org/rfc/rfc9562.html), email address, phone number, or other sensitive information.
| Yes |
### Response parameters [#response-parameters]
| Parameter | Type | Description |
| :---------- | :----- | :-------------------------------------------- |
| `data` | JSON | The response details. |
| `timestamp` | Number | The Unix timestamp (ms) of the HTTP response. |
| `username` | String | The user ID. |
| `groupname` | String | The chat group name. |
## Authorization [#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:
```html
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](/en/realtime-media/im/build/secure-access-and-authentication/authentication).
## Create/Add a reaction [#createadd-a-reaction]
This method creates or adds a reaction to a specified message in one-to-one chats or chat groups. A maximum of 20 reactions can be added for one message. For one message, if many users add the same reaction, these reactions are counted as one reaction. A message can have a maximum of 20 reactions. To raise the limit, contact [support@agora.io](mailto\:support@agora.io).
### HTTP request [#http-request]
```html
POST https://{host}/app-id/{app_id}/reaction/user/{userId}
```
#### Path parameter [#path-parameter]
| Parameter | Type | Description | Required |
| :-------- | :----- | :------------------------------- | :------- |
| `userId` | String | The user ID of the current user. | Yes |
For other parameters and the detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | `application/json` | Yes |
| `Authorization` | String | The 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 [#request-body]
| Parameter | Type | Description |
| :-------- | :----- | :------------------------------------------------------------------------------------- |
| `msg_Id` | String | The message ID to which you want to add the reaction. |
| `message` | String | The ID of the emoji, same as that on the client. The maximum length is 128 characters. |
### HTTP Response [#http-response]
#### Response body [#response-body]
If the returned HTTP status code is `200`, the request succeeds, and the `data` in the response contains the following fields:
| Parameter | Type | Description |
| ------------------- | ------- | --------------------------------------------------------------------------------- |
| `requestStatusCode` | String | The status code of this request. `ok` means that the request succeeds. |
| `id` | String | The reaction ID. |
| `msgId` | String | The message ID. |
| `msgType` | String | The message type: `chat`: One-to-one chat. `groupchat`: Group chat. |
| `groupId` | String | The group ID. If the message type is `chat`, the server returns null. |
| `reaction` | String | The ID of the emoji added as the reaction, same as `message` in the request body. |
| `createAt` | Instant | The time when the reaction is created. |
| `updateAt` | Instant | The time when the reaction is updated. |
For other fields and the detailed descriptions, see [Public parameters](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example]
#### Request example [#request-example]
```bash
curl -g -X POST 'http://XXXX/app-id/XXXX/reaction/user/e1' -H 'Authorization: Bearer {YourAppToken}' -H 'Content-Type: application/json' --data-raw '{
"msgId":"997625372793113144",
"message":"emoji_40"
}'
```
#### Response example [#response-example]
```json
{
"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"
}
}
```
## Retrieve reactions with message IDs [#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 [#http-request-1]
```bash
GET https://{host}/app-id/{app_id}/reaction/user/{userId}?msgIdList={N,M}&msgType={msgType}&groupId={groupId}
```
#### Path parameter [#path-parameter-1]
| Parameter | Type | Description | Required |
| :-------- | :----- | :------------------------------- | :------- |
| `userId` | String | The user ID of the current user. | Yes |
For other parameters and the detailed descriptions, see [Common parameters](#param).
#### Query parameter [#query-parameter]
| Parameter | Type | Description | Required |
| :---------- | :----- | :-------------------------------------------------------------------------------------------------------- | :------- |
| `msgIdList` | Array | The ID of the message from which you attempt to retrieve reactions. You can pass in up to 20 message IDs. | Yes |
| `msgType` | String | The chat type: `chat`: One-to-one chat. `groupchat`: Group chat. | Yes |
| `groupId` | String | The ID of the group. This parameter is only required if you set `msgType` to `groupchat`. | No |
#### Request header [#request-header-1]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | `application/x-www-form-urlencoded` | Yes |
| `Authorization` | String | The 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 [#http-response-1]
#### Response body [#response-body-1]
If the returned HTTP status code is `200`, the request succeeds, and the `data` in the response contains the following fields:
| Parameter | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `requestStatusCode` | String | The status code of this request. `ok` means that the request succeeds. |
| `msgId` | String | The message ID. |
| `reactionId` | String | The reaction ID returned in the response body of [Create a reaction](#create). |
| `reaction` | String | The emoji ID that is the same as the `message` parameter specified in the request body when [adding a reaction](#create). |
| `count` | Number | The number of users that have added this reaction to the message. |
| `state` | Bool | Whether the user sending this request has added a reaction to this message: `true`: Yes. `false`: No. |
| `userList` | Array | The 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](./http-status-codes) for possible reasons.
### Example [#example-1]
#### Request example [#request-example-1]
```bash
curl -g -X GET 'http://XXXX/app-id/XXXX/reaction/user/{{userId}}?msgIdList=msgId1&msgType=chat' -H 'Authorization: Bearer {YourAppToken}'
```
#### Response example [#response-example-1]
```json
{
"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"
]
}
]
}
]
}
```
## Delete a reaction [#delete-a-reaction]
This method deletes a reaction.
### HTTP request [#http-request-2]
```bash
DELETE https://{host}/app-id/{app_id}/reaction/user/{userId}
```
#### Path parameter [#path-parameter-2]
| Parameter | Type | Description | Required |
| :-------- | :----- | :------------------------------- | :------- |
| `userId` | String | The user ID of the current user. | Yes |
For other parameters and the detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-2]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | `application/x-www-form-urlencoded` | Yes |
| `Authorization` | String | The 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 [#query-parameters]
| Parameter | Type | Description | Required |
| --------- | ------ | -------------------------------------------------- | -------- |
| `msgId` | String | The message ID. | Yes |
| `message` | String | The ID of the emoji that is added as the reaction. | Yes |
### HTTP Response [#http-response-2]
#### Response body [#response-body-2]
If the returned HTTP status code is `200`, the request succeeds, and the `data` in the response contains the following fields:
| Parameter | Type | Description |
| ------------------- | ------ | ---------------------------------------------------------------------- |
| `requestStatusCode` | String | The status code of this request. `ok` means that the request succeeds. |
| `timestamp` | Long | The Unix timestamp of this response, in milliseconds. |
For other fields and the detailed descriptions, see [Common parameters](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-2]
#### Request example [#request-example-2]
```bash
curl -g -X DELETE 'http://XXXX/app-id/XXXX/reaction/user/wz?msgId=997625372793113144&message=emoji_40' -H 'Authorization: Bearer {YourAppToken}'
```
#### Response example [#response-example-2]
```json
{
"requestStatusCode": "ok",
"timestamp": 1645774821181
}
```
## Retrieve the detailed information of the reaction [#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 [#http-request-3]
```bash
https://{host}/app-id/{app_id}/reaction/user/{userId}/detail?msgId={msgId}&message={message}&limit={limit}&cursor={cursor}
```
#### Path parameter [#path-parameter-3]
| Parameter | Type | Description | Required |
| :-------- | :----- | :------------------------------- | :------- |
| `userId` | String | The user ID of the current user. | Yes |
For other parameters and the detailed descriptions, see [Common parameters](#param).
#### Query parameter [#query-parameter-1]
| Parameter | Type | Description | Required |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `msgId` | String | The message ID. | Yes |
| `message` | String | The ID of the emoji that is added as the reaction. | Yes |
| `limit` | Number | The number of users that added the reaction on each page when you retrieve the users with pagination. The value range is \[1,50]. The default value is 50. | No |
| `cursor` | String | The cursor for specifying where to retrieve data if you retrieve the users with pagination. | No |
If the pagination parameters are specified, the server returns the users that added the reaction in the ascending order of when reactions are added. If the pagination parameters are not specified, the server returns the first 50 users that added the reaction.
#### Request header [#request-header-3]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | `application/x-www-form-urlencoded` | Yes |
| `Authorization` | String | The 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 [#http-response-3]
#### Response body [#response-body-3]
If the returned HTTP status code is `200`, the request succeeds, and the `data` in the response contains the following fields:
| Parameter | Type | Description |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| `requestStatusCode` | String | The status code of this request. `ok` means that the request succeeds. |
| `reactionId` | String | The reaction ID. |
| `reaction` | String | The emoji ID that is the same as the `message` parameter specified in the request body when [adding a reaction](#create). |
| `count` | Number | The number of users that have added the reaction. |
| `state` | Bool | Whether the user sending this request has added a reaction to this message: `true`: Yes. `false`: No. |
| `userList` | Array | The list of the users that have added this reaction. Users are listed in the ascending order of the reaction addition time. |
| `cursor` | String | The cursor that indicates that starting position of the next query. |
For other fields and the detailed descriptions, see [Common parameters](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-3]
#### Request example [#request-example-3]
```bash
// Starts querying from the first page
curl -g -X GET 'http://XXXX/app-id/XXXX/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&limit=50' -H 'Authorization: Bearer {YourAppToken}'
// Starts querying from the second page
curl -g -X GET 'http://XXXX/app-id/XXXX/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&cursor=944330529971449164&limit=50' -H 'Authorization: Authorization: Bearer {YourAppToken}'
```
#### Response example [#response-example-3]
```json
{
"requestStatusCode": "ok",
"timestamp": 1645776986146,
"data": {
"reactionId": "946463470818405943",
"reaction": "message123456",
"userCount": 1,
"state": true,
"userList": [
"wz1"
],
"cursor": "946463471296555192"
}
}
```
## Status codes [#status-codes]
For details, see [HTTP Status Codes](./http-status-codes).