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

• 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 enables you to implement user system management, including user registration, retrieving users, modifying user attributes, and deleting users.

Name	Method	Request	Description
Registering a user	POST	/{org_name}/{app_name}/users	Creates a user account.
Registering multiple users	POST	/{org_name}/{app_name}/users	Creates multiple user accounts.
Retrieving a user	GET	/{org_name}/{app_name}/users/{username}	Retrieves the information of the specified user.
Retrieving multiple users.	GET	/{org_name}/{app_name}/users	Retrieves the information of the specified users.
Deleting a user	DELETE	/{org_name}/{app_name}/users/{username}	Deletes the specified user.
Deleting multiple users	DELETE	/{org_name}/{app_name}/users	Deletes all the users in the app.
Modifying the password	PUT	/{org_name}/{app_name}/users/{username}/password	Changes the user's password.
Banning a user	POST	/{org_name}/{app_name}/users/{username}/deactivate	Bans a user.
Unbanning a user	POST	/{org_name}/{app_name}/users/{username}/activate	Unbans a user.
Forcing a user offline	POST	/{org_name}/{app_name}/users/{username}/disconnect	Forcibly moves a user offline.
Querying the online state	GET	/{org_name}/{app_name}/users/{username}/status	Queries whether a user is online.
Querying the online state of multiple users	POST	/{org_name}/{app_name}/users/batch/status	Queries whether multiple users are online.
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.
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.

This group of methods enables you to set the push message display mode, display nickname, and do-not-disturb mode.

Name	Method	Request	Description
Setting the display nickname	PUT	/{org_name}/{app_name}/users/{username}	Sets the display nickname of the push message.
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.
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.

This group of methods enables you to send text, image, voice, video, pass-through, extension, file, custom, and other types of messages, as well as to upload and download files from the server.

Name	Method	Request	Description
Sending a message	POST	/{org_name}/{app_name}/messages	App admins use this method to send messages to users or groups, and support sending text, image, voice, video, pass-through, extension, and file messages.
Uploading files	POST	/{org_name}/{app_name}/chatfiles	Uploads voice and image files.
Downloading files	POST	/{org_name}/{app_name}/chatfiles/{uuid}	Downloads voice and image files.
Retrieving historical messages	GET	/{org_name}/{app_name}/chatmessages/${time}	Retrieves chat historical messages
Retrieving the conversation list	GET	/{org_name}/{app_name}/user/{username}/user_channels	Retrieves a list of conversations of the specified user.
Recalling a message	POST	{org_name}/{app_name}/messages/recall	Recalls a message two minutes after it is sent.
Deleting conversations from the server	DELETE	/{orgName}/{appName}/users/{userName}/user_channel	Deletes the conversation from the server.

This group of methods enables you to set, retrieve, and delete user attributes.

Name	Method	Request	Description
Setting user attributes	PUT	/{org_name}/{app_name}/metadata/user/{username}	Sets the user attributes for the specified user.
Retrieving user attributes	GET	/{org_name}/{app_name}/metadata/user/{username}	Retrieves all the user attributes of the specified user.
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.
Deleting user attributes	DELETE	/{org_name}/{app_name}/metadata/user/{username}	Deletes all the user attributes for the specified user.
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.

This group of methods enables you to manage the user's contact list and block list.

Name	Method	Request	Description
Adding a contact	POST	/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}	Adds the specified user as a contact.
Removing a contact	DELETE	/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}	Removes the specified user from the contact list.
Retrieving a contact list	GET	/{org_name}/{app_name}/users/{owner_username}/contacts/users	Retrieves the contact list.
Retrieving a block list	GET	/{org_name}/{app_name}/users/{owner_username}/blocks/users	Retrieves the block list.
Adding user to block list	POST	/{org_name}/{app_name}/users/{owner_username}/blocks/users	Add the specified user to the block list.
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.

This group of methods enables you to create, retrieve, modify, and delete chat groups.

Name	Method	Request	Description
Retrieving all chat groups in the app (Pagination)	GET	/{org_name}/{app_name}/chatgroups	Retrieves the information of all the groups in the app.
Retrieving all the chat groups the user joins	GET	/{app_name}/users/{username}/joined_chatgroups	Retrieves all the groups the user joins by specifying the user name.
Retrieving chat group details	GET	/{org_name}/{app_name}/chatgroups/{group_ids}	Retrieves the information of the group details by specifying the group ID.
Creating a chat group	POST	/{org_name}/{app_name}/chatgroups	Creates a chat group.
Modifying chat group information	PUT	/{org_name}/{app_name}/chatgroups/{group_id}	Modifies the group information.
Deleting a chat group	DELETE	/{org_name}/{app_name}/chatgroups/{group_id}	Deletes a chat group.

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
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.
Adding a chat group member	POST	/{org_name}/{app_name}/chatgroups/{group_id}/users/{username}	Adds a user to the group member list.
Adding multiple group members	POST	/{org_name}/{app_name}/chatgroups/{chatgroupid}/users	Adds multiple users to the group member list.
Removing a chat group member	DELETE	/{org_name}/{app_name}/chatgroups/{group_id}/users/{username}	Removes the specified user from the group member list.
Removing multiple chat group members	DELETE	/{org_name}/{app_name}/chatgroups/{group_id}/users/{usernames}	Removes the specified users from the group members list.
Retrieving chat group admin list	GET	/{org_name}/{app_name}/chatgroups/{group_id}/admin	Retrieves the group admin list.
Adding a chat group admin.	POST	/{org_name}/{app_name}/chatgroups/{group_id}/admin	Adds the specified user to the group admin list.
Removing a chat group admin	DELETE	/{org_name}/{app_name}/chatgroups/{group_id}/admin/{oldadmin}	Removes the specified user from the group admin list.
Transferring chat group ownership	PUT	/{org_name}/{app_name}/chatgroups/{groupid}	Transfers the group owner privileges.

This group of methods enables you to create, retrieve, modify, and delete chat rooms.

Name	Method	Request	Description
Retrieving all chat rooms	GET	/{org_name}/{app_name}/chatrooms	Retrieves the information of all the chat rooms in the app.
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.
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.
Creating a chat room	POST	/{org_name}/{app_name}/chatrooms	Creates a new chat room.
Modifying chat room information	PUT	/{org_name}/{app_name}/chatrooms/{chatroom_id}	Modifies the chat room information.
Deleting a chat room	DELETE	/{org_name}/{app_name}/chatrooms/{chatroom_id}	Deletes a chat room.

This group of methods enables you to add, retrieve, modify, and delete members from the chat room.

Name	Method	Request	Description
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.
Adding a chat room member	POST	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}	Adds the specified user to the chat room member list.
Adding multiple chat room members	POST	/{org_name}/{app_name}/chatrooms/{chatroomid}/users	Adds multiple specified users to the chat room member list.
Removing a chat room member	DELETE	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}	Removes the specified user from the chat room member list.
Removing multiple chat room members	DELETE	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}	Removes the specified users from the chat room member list.
Retrieving chat room admin list	GET	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin	Retrieves the chat room admin list.
Adding a chat room admin	POST	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin	Adds the specified user to the chat room admin list.
Removing a chat room admin	DELETE	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin}	Remove the specified user from the chat room admin list.

This group of methods enable 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
Globally mute a specified user	POST	/{orgName}/{appName}/mutes	Mutes a specified user in one-to-one chats, chat groups, or chat rooms.
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.
Retrieve all globally muted users	GET	/{orgName}/{appName}/mutes	Retrieves all the users that have been globally muted in the app.

This group of methods enable your chat users to reply the message with emojis.

Name	Method	Request	Description
Create a reaction	POST	/{org_name}/{app_name}/reaction/user/{userId}	Creates or adds a reaction to a specified message.
Retrieve reactions with message IDs	GET	/{org_name}/{app_name}/reaction/user/{userId}	Retrieves the information of the reaction according to the message ID.
Delete a reaction	DELETE	/{org_name}/{app_name}/reaction/user/{userId}	Deletes a reaction.
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.

The Chat RESTful APIs requires 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 API 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 API only supports the HTTPS protocol.

• Request: See the code sample 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.