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.

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:

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.

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

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

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.

This group of methods enables you to send text, image, voice, video, CMD, extension, file, custom, and other types of messages, as well as uploading and downloading 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
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

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

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

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

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

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

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

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

This group of methods enable you to set the presence of a user, subscribe to the presence of multiple users, retrieve the presence status of multiple users, and retrieve the subscriptions of a user.

Name	Method	Request	Description	Rate Limits
Setting the presence status of a user	POST	/{org_name}/{app_name}/users/{username}/presence/{resource}/{status}	Sets the presence status of a user by user ID.	50/second
Subscribing to the presence status of multiple users	POST	/{org_name}/{app_name}/users/{username}/presence/{expiry}	Subscribes to the presence status of multiple users.	50/second
Retrieving the presence status of multiple users	POST	/{org_name}/{app_name}/users/{username}/presence	Retrieves the presence status of multiple users.	50/second
Unsubscribing from the presence status of multiple users	DELETE	/{org_name}/{app_name}/users/{username}/presence	Unsubscribes from the presence status of multiple users.	50/second
Retrieving the subscriptions of a user	GET	/{org_name}/{app_name}/users/{username}/presence/sublist?pageNum=1&pageSize=100	Retrieves the subscriptions of a user.	50/second

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

This group of methods enable you to create a thread, modify a thread, delete a thread, and retrieve threads.

| Name | Method | Request | Description | Rate Limits | | :------------- | :----- | :---------------------------- | :--------------------- | | Creating a thread | POST | /{org_name}/{app_name}/thread | Creates a thread. | 100/second | | Modifying a thread | PUT | /{org_name}/{app_name}/thread/{thread_id} | Modifies a thread. | 100/second | | Deleting a thread | DELETE | /{org_name}/{app_name}/thread/{thread_id} | Deletes a thread. | 100/second | | Retrieving all the threads under the app | GET | /{org_name}/{app_name}/thread?limit={limit}&cursor={cursor}&sort={sort} | Retrieves all the threads under the app | 100/second | | Retrieving all the threads a user joins under the app | GET | /{org_name}/{app_name}/threads/user/{username}?limit={limit}&cursor={cursor}&sort={sort} | Retrieves all the threads a user joins under the app | 100/second | | Retrieving all the threads a user joins under a chat group | GET | /{org_name}/{app_name}/threads/chatgroups/{group_id}/user/{username}?limit={limit}&cursor={cursor}&sort={sort} | Retrieves all the threads a user joins by user ID and group ID. | 100/second |

This group of methods enable you to join a thread and remove members from the thread.

Name	Method	Request	Description	Rate Limits
Retrieving thread members	GET	/{org_name}/{app_name}/thread/{thread_id}/users?limit={N}&cursor={cursor}	Retrieves all the members in the specified thread.	100/second
Adding multiple users to a thread	POST	/{org_name}/{app_name}/thread/{thread_id}/users	Adds multiple users to the specified thread.	100/second
Removing multiple thread members	DELETE	/{org_name}/{app_name}/threads/{thread_id}/users	Removes multiple users from the specified thread.	100/second

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:

_1

Authorization: Bearer ${token}

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.

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.

To ensure communication security, the Chat RESTful APIs only support the HTTPS protocol.

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