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 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.

Common parameters

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

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.	Yes
`org_name`	String	The 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_name`	String	The 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
`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) 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

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

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:

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

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

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

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 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:

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 chat 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.

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

Example

Request example

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

Response example

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

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

GET https://{host}/{org_name}/{app_name}/reaction/user/{userId}

Path parameter

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

Request header

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 parameter

Parameter	Type	Description	Required
`msgIdList`	Array	The message IDs whose reaction you want to retrieve.	Yes
`msgType`	String	The message type: `chat`: One-to-one chat. `groupchat`: Group chat.	Yes
`groupId`	String	The chat group ID. If you set `msgType` as `groupchat`, you must specify a group ID.

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:

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 data of the response body of Create a reaction.
`reaction`	String	The ID of the emoji that is added as the reaction.
`count`	Number	The number of users that have added this reaction to the message.
`state`	Boolean	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 for possible reasons.

Example

Request example

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

Response example

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

Delete a reaction

This method deletes a reaction.

HTTP request

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

Path parameter

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

Reqest header

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

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

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.
`timestamp`	Long	The Unix timestamp of this response, in miliseconds.

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

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

Response example

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

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

GET https://{host}/{org_name}/{app_name}/reaction/user/{userId}/detail

Path parameter

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

Request header

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

Request body

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 reactions retrieved on each page when you retrieve the reactions with pagination. The value range is [1,100]. The default value is 100.	No
`cursor`	String	The starting page from which to retrieve data if you retrieve the reactions with pagination.

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:

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 ID of the emoji that is added as the reaction.
`count`	Number	The number of users that have added the reaction.
`state`	String	The state of the this request.
`userList`	Array	The list of the users that have added this reaction. It only contains the three user IDs that last used reaction.
`cursor`	String	The starting page from which to retrieve data if you retrieve the reactions with pagination.

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

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

Response example

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

Status codes

For details, see HTTP Status Codes.

Request parameters ​

Response parameters ​

Request parameters

Response parameters