Chat RESTful API overview
Chat provides RESTful APIs through the REST platform. You can send HTTP requests to the Agora server through your business server to realize real-time communication on the server side.
REST Platform Architecture
The Chat REST platform provides a multi-tenant architecture to manage resources in the form of a Collection. A Collection contains the following:
- Database
- Organizations (orgs)
- Apps (apps)
- Users (users)
- Chat groups (chatgroups)
- Chat messages (chatmessages)
- Chat files (chatfiles)
The user data of different orgs is isolated from each other. Under the same org, the user data of different apps is also isolated from each other. The data structure of an org is as follows:
Prerequisites
Ensure that you meet the following requirements before calling the Chat RESTful APIs:
- You have enabled and configured Chat in the Console.
- You have retrieved an app token from the app server. For details, see Authentication with App Token.
Features
User system integration
This group of methods enable you to implement user system management, including user registration, retrieving users, modifying user attributes, and deleting users.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Registering a user | POST | /{org_name}/{app_name}/users | Creates a user account. | 100/second |
| Registering multiple users | POST | /{org_name}/{app_name}/users | Creates multiple user accounts. | 100/second |
| Retrieving a user | GET | /{org_name}/{app_name}/users/{username} | Retrieves the information of the specified user. | 100/second |
| Retrieving multiple users. | GET | /{org_name}/{app_name}/users | Retrieves the information of the specified users. | 100/second |
| Deleting a user | DELETE | /{org_name}/{app_name}/users/{username} | Deletes the specified user. | 100/second |
| Deleting multiple users | DELETE | /{org_name}/{app_name}/users | Deletes all the users in the app. | 30/second |
| Banning a user | POST | /{org_name}/{app_name}/users/{username}/deactivate | Bans a user. | 100/second |
| Unbanning a user | POST | /{org_name}/{app_name}/users/{username}/activate | Unbans a user. | 100/second |
| Forcing a user offline | POST | /{org_name}/{app_name}/users/{username}/disconnect | Forcibly moves a user offline. | 100/second |
| Querying the online state | GET | /{org_name}/{app_name}/users/{username}/status | Queries whether a user is online. | 100/second |
| Querying the online state of multiple users | POST | /{org_name}/{app_name}/users/batch/status | Queries whether multiple users are online. | 50/second |
| Querying the number of offline messages | GET | /{org_name}/{app_name}/users/{owner_username}/offline_msg_count | Queries the number of offline messages a user has. | 100/second |
| Querying the delivery state of an offline message | GET | /{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id} | Queries the delivery state of an offline message. | 100/second |
Push
This group of methods enables you to set the push message display mode, display nickname, and do-not-disturb mode.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Setting the display nickname | PUT | /{org_name}/{app_name}/users/{username} | Sets the display nickname of the push message. | 100/second |
| Setting the display options | PUT | /{org_name}/{app_name}/users/{username} | Sets whether the push messages are displayed as notifications only or details are visible. | 100/second |
| Setting do-not-disturb (DND) | PUT | /{org_name}/{app_name}/users/{username} | Sets whether to enable DND, and the time to enable and disable DND. | 100/second |
| Sending push notifications to users | POST | /{org_name}/{app_name}/push/single | Sends push notifications to one or more users by specifying user IDs. | 1200/minute |
| Sending push notifications by labels | POST | /{org_name}/{app_name}/push/list/label | Sends push notifications to all users under one label, or the intersection of users under multiple labels. | 1200/minute, the number of concurrent ongoing tasks cannot exceed 3 |
| Sending push notifications to all users under the app | POST | /{org_name}/{app_name}/push/task | Sends push notifications to all users under the app. | 5/minute & 100 times per day, the number of concurrent ongoing tasks cannot exceed 3 |
Push label
The total rate limit of the following methods is 100/second.
| Name | Method | Request | Description |
|---|---|---|---|
| Creating a push label | POST | /{org_name}/{app_name}/push/label | Sets a push label to group targeting users, to implement a bespoke push. |
| Querying the detailed information of the specified push label. | GET | /{org_name}/{app_name}/push/label/{labelname} | Retrieves the detailed information of the specified push label. |
| Querying the detailed information of push labels by page | GET | /{org_name}/{app_name}/push/label | Retrieves the detailed information of multiple push labels by page. |
| Deleting a push label | DELETE | /{org_name}/{app_name}/push/label/{labelname} | Deletes the specified push label. You can delete one push label at each call. |
| Adding users to a push label | POST | /{org_name}/{app_name}/push/label/{labelname}/user | Adds one or more users to the specified push label. You can add a maximum of 100 users at each call. |
| Querying the specified user under the specified push label | GET | /{org_name}/{app_name}/push/label/{labelname}/user/{member} | Retrieves the detailed information of the specified user under the specified push label. |
| Querying the detailed information of users under the specified push label by page | GET | /{org_name}/{app_name}/push/label/{labelname}/user | Retrieves the detailed information of one or more users under the specified push label by page. |
| Removing users from a push label | DELETE | /{org_name}/{app_name}/push/label/{labelname}/user | Removes one or more users from the specified push label. You can remove a maximum of 100 users at each call. |
Sending messages and uploading/downloading files
This group of methods enables you to send text, image, voice, video, CMD, extension, file, custom, and other types of messages, as well as to upload and download files from the server.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Sending a message | POST | /{org_name}/{app_name}/messages | App admins use this method to send messages to users, chat groups, and chat rooms. This method supports sending text, image, voice, video, command, and file messages. | 100/second |
| Uploading files | POST | /{org_name}/{app_name}/chatfiles | Uploads voice and image files. | 100/second |
| Downloading files | POST | /{org_name}/{app_name}/chatfiles/{file_uuid} | Downloads voice and image files. | 100/second |
| Retrieving historical messages | GET | /{org_name}/{app_name}/chatmessages/${time} | Retrieves chat historical messages | 10/minute |
| Retrieving the conversation list | GET | /{org_name}/{app_name}/user/{username}/user_channels | Retrieves a list of conversations of the specified user. | 100/second & 5/minute each user |
| Recalling a message | POST | {org_name}/{app_name}/messages/recall | Recalls a message within two minutes after it is sent. | 100/second |
| Deleting conversations from the server | DELETE | /{orgName}/{appName}/users/{userName}/user_channel | Deletes the conversation from the server. | 100/second |
User attributes
This group of methods enables you to set, retrieve, and delete user attributes.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Setting user attributes | PUT | /{org_name}/{app_name}/metadata/user/{username} | Sets the user attributes for the specified user. | 100/second |
| Retrieving user attributes | GET | /{org_name}/{app_name}/metadata/user/{username} | Retrieves all the user attributes of the specified user. | 100/second |
| Retrieving the user attributes of multiple users | POST | /{org_name}/{app_name}/metadata/user/get | Retrieves multiple users' attributes by specifying the user name list and user attribute list. | 100/second |
| Deleting user attributes | DELETE | /{org_name}/{app_name}/metadata/user/{username} | Deletes all the user attributes for the specified user. | 100/second |
| Retrieving the total size of user attributes | GET | /{org_name}/{app_name}/metadata/user/capacity | Gets the total size of user attributes for all the users in the app. | 100/second |
Contact management
This group of methods enables you to manage the user's contact list and block list.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Adding a contact | POST | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | Adds the specified user as a contact. | 100/second |
| Removing a contact | DELETE | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | Removes the specified user from the contact list. | 100/second |
| Retrieving a contact list | GET | /{org_name}/{app_name}/users/{owner_username}/contacts/users | Retrieves the contact list. | 100/second |
| Retrieving a block list | GET | /{org_name}/{app_name}/users/{owner_username}/blocks/users | Retrieves the block list. | 50/second |
| Adding user to block list | POST | /{org_name}/{app_name}/users/{owner_username}/blocks/users | Add the specified user to the block list. | 50/second |
| Removing user from block list | DELETE | /{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username} | Removes the specified user from the block list. | 50/second |
Chat group management
This group of methods enables you to create, retrieve, modify, and delete chat groups.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Retrieving all chat groups in the app by page | GET | /{org_name}/{app_name}/chatgroups?limit={N}&cursor={cursor} | Retrieves the information of all the groups in the app by page. | 100/second |
| Retrieving all the chat groups the user joins | GET | /{org_name}/{app_name}/users/{username}/joined_chatgroups | Retrieves all the groups the user joins by specifying the user name. | 100/second |
| Retrieving chat group details | GET | /{org_name}/{app_name}/chatgroups/{group_ids} | Retrieves group details by specifying the group ID. | 100/second |
| Creating a chat group | POST | /{org_name}/{app_name}/chatgroups | Creates a chat group. | 100/second |
| Banning a chat group | POST | /{org_name}/{app_name}/chatgroups/{group_id}/disable | Bans the specified chat group. Groups are typically banned when too many users or messages violate community guidelines. | 100/second |
| Unbanning a chat group | POST | /{org_name}/{app_name}/chatgroups/{group_id}/enable | Lifts a ban on the specified chat group. | 100/second |
| Modifying chat group information | PUT | /{org_name}/{app_name}/chatgroups/{group_id} | Modifies the group information. | 100/second |
| Deleting a chat group | DELETE | /{org_name}/{app_name}/chatgroups/{group_id} | Deletes a chat group. | 100/second |
Chat group member management
This group of methods enables you to manage chat group members, including adding and removing chat group members, transferring chat group ownership, and retrieving lists of chat group admins and members.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Retrieving chat group member list (Pagination) | GET | /{org_name}/{app_name}/chatgroups/{group_id}/users | Retrieves the member list of the chat group by pagination. | 100/second |
| Adding a chat group member | POST | /{org_name}/{app_name}/chatgroups/{group_id}/users/{username} | Adds a user to the group member list. | 100/second |
| Adding multiple group members | POST | /{org_name}/{app_name}/chatgroups/{chatgroupid}/users | Adds multiple users to the group member list. | 100/second |
| Removing a chat group member | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/users/{username} | Removes the specified user from the group member list. | 100/second |
| Removing multiple chat group members | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/users/{usernames} | Removes the specified users from the group member list. | 100/second |
| Retrieving chat group admin list | GET | /{org_name}/{app_name}/chatgroups/{group_id}/admin | Retrieves the group admin list. | 100/second |
| Adding a chat group admin | POST | /{org_name}/{app_name}/chatgroups/{group_id}/admin | Adds the specified user to the group admin list. | 100/second |
| Removing a chat group admin | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/admin/{oldadmin} | Removes the specified user from the group admin list. | 100/second |
| Transferring chat group ownership | PUT | /{org_name}/{app_name}/chatgroups/{groupid} | Transfers the group owner privileges. | 100/second |
Chat room management
This group of methods enables you to create, retrieve, modify, and delete chat rooms.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Retrieving all chat rooms by page | GET | /{org_name}/{app_name}/chatrooms?limit={N}&cursor={cursor} | Retrieves the information of all the chat rooms in the app by page. | 50/second |
| Retrieving chat rooms a user joins | GET | /{org_name}/{app_name}/users/{username}/joined_chatrooms | Retrieves the chat rooms that a user joins by specifying the username. | 50/second |
| Retrieving chat room details | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id} | Retrieves the details of the chat room by specifying the chat room ID. | 100/second |
| Creating a chat room | POST | /{org_name}/{app_name}/chatrooms | Creates a new chat room. | 50/second |
| Modifying chat room information | PUT | /{org_name}/{app_name}/chatrooms/{chatroom_id} | Modifies the chat room information. | 100/second |
| Deleting a chat room | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id} | Deletes a chat room. | 100/second |
| Setting custom attributes | PUT | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username} | Adds new custom chat room attributes or modifies existing ones set by the current user. | 100/second |
| Retrieving custom attributes | POST | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id} | Retrieves the specified custom attributes of a chat room. | 100/second |
| Forcibly setting custom attributes | PUT | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced | In addition to adding new custom attributes or modifying the existing ones set by the current user, this method can also be used to overwrite the custom attributes set by others. | 100/second |
| Removing custom attributes | DELETE | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username} | Removes custom attributes set by the current user. This method is only used to remove the key-value pairs set by the current user. | 100/second |
| Forcibly removing custom attributes | DELETE | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced | In addition to removing the custom attributes set by the current user, this method can also be used to remove custom attributes set by others. | 100/second |
Chat room member management
This group of methods enables you to add, retrieve, modify, and delete members from the chat room.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Retrieving chat room member list (Pagination) | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/users | Retrieves the member list of the chat room by pagination. | 100/second |
| Adding a chat room member | POST | /{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username} | Adds the specified user to the chat room member list. | 100/second |
| Adding multiple chat room members | POST | /{org_name}/{app_name}/chatrooms/{chatroomid}/users | Adds multiple specified users to the chat room member list. | 100/second |
| Removing a chat room member | DELETE | /{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username} | Removes the specified user from the chat room member list. | 100/second |
| Removing multiple chat room members | DELETE | /{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames} | Removes the specified users from the chat room member list. | 100/second |
| Retrieving chat room admin list | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/admin | Retrieves the chat room admin list. | 100/second |
| Adding a chat room admin | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/admin | Adds the specified user to the chat room admin list. | 100/second |
| Removing a chat room admin | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin} | Removes the specified user from the chat room admin list. | 100/second |
Global mute
This group of methods enables you to mute any user ID in one-to-one chats, group chats, or chat rooms, preventing these users from sending messages to other chat users, chat groups, or chat rooms.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Globally mute a specified user | POST | /{orgName}/{appName}/mutes | Mutes a specified user in one-to-one chats, chat groups, or chat rooms. | 100/second |
| Query the detailed information of global-mute | GET | /{orgName}/{appName}/mutes/username | Queries the detailed information of the global-mute settings of the specified user in one-to-one chats, group chats, or chatrooms. | 100/second |
| Retrieve all globally muted users | GET | /{orgName}/{appName}/mutes | Retrieves all the users that have been globally muted in the app. | 100/second |
Reaction
This group of methods enable your chat users to reply the message with emojis.
| Name | Method | Request | Description | Rate Limits |
|---|---|---|---|---|
| Create a reaction | POST | /{org_name}/{app_name}/reaction/user/{userId} | Creates or adds a reaction to a specified message. | 100/second |
| Retrieve reactions with message IDs | GET | /{org_name}/{app_name}/reaction/user/{userId} | Retrieves the information of the reaction according to the message ID. | 100/second |
| Delete a reaction | DELETE | /{org_name}/{app_name}/reaction/user/{userId} | Deletes a reaction. | 100/second |
| Retrieve the detailed information of the reaction | GET | /{org_name}/{app_name}/reaction/user/{userId}/detail | Retrieves the detailed information of the reaction by specifying the message ID and reaction ID. | 100/second |
Request structure
Authorization
The 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:
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. The Chat RESTful APIs only supports authenticating users using app tokens. For details, see Authentication using App Token.
Server address
Under the same project, all requests are sent to the same domain name. For how to get the domain name, see Get the information of the Chat project.
Protocol
To ensure communication security, the Chat RESTful APIs only support the HTTPS protocol.
Data Format
- Request: See the sample code of each API for the data format of the request.
- Response: The format of the response is JSON.
All request URLs and request bodies are case sensitive.