Skip to main content

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:

1642333129463

Prerequisites

Ensure that you meet the following requirements before calling the Chat RESTful APIs:

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.

NameMethodRequestDescriptionRate Limits
Registering a userPOST/{org_name}/{app_name}/usersCreates a user account.100/second
Registering multiple usersPOST/{org_name}/{app_name}/usersCreates multiple user accounts.100/second
Retrieving a userGET/{org_name}/{app_name}/users/{username}Retrieves the information of the specified user.100/second
Retrieving multiple users.GET/{org_name}/{app_name}/usersRetrieves the information of the specified users.100/second
Deleting a userDELETE/{org_name}/{app_name}/users/{username}Deletes the specified user.100/second
Deleting multiple usersDELETE/{org_name}/{app_name}/usersDeletes all the users in the app.30/second
Banning a userPOST/{org_name}/{app_name}/users/{username}/deactivateBans a user.100/second
Unbanning a userPOST/{org_name}/{app_name}/users/{username}/activateUnbans a user.100/second
Forcing a user offlinePOST/{org_name}/{app_name}/users/{username}/disconnectForcibly moves a user offline.100/second
Querying the online stateGET/{org_name}/{app_name}/users/{username}/statusQueries whether a user is online.100/second
Querying the online state of multiple usersPOST/{org_name}/{app_name}/users/batch/statusQueries whether multiple users are online.50/second
Querying the number of offline messagesGET/{org_name}/{app_name}/users/{owner_username}/offline_msg_countQueries the number of offline messages a user has.100/second
Querying the delivery state of an offline messageGET/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}Queries the delivery state of an offline message.100/second

Message push

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

NameMethodRequestDescriptionRate Limits
Setting the display nicknamePUT/{org_name}/{app_name}/users/{username}Sets the display nickname of the push message.100/second
Setting the display optionsPUT/{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 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.

NameMethodRequestDescriptionRate Limits
Sending a messagePOST/{org_name}/{app_name}/messagesApp admins use this method to send messages to users or groups, including text, image, voice, video, command, and file messages.100/second
Uploading filesPOST/{org_name}/{app_name}/chatfilesUploads voice and image files.100/second
Downloading filesPOST/{org_name}/{app_name}/chatfiles/{uuid}Downloads voice and image files.100/second
Retrieving historical messagesGET/{org_name}/{app_name}/chatmessages/${time}Retrieves chat historical messages10/minute
Retrieving the conversation listGET/{org_name}/{app_name}/user/{username}/user_channelsRetrieves a list of conversations of the specified user.100/second & 5/minute each user
Recalling a messagePOST{org_name}/{app_name}/messages/recallRecalls a message within two minutes after it is sent.100/second
Deleting conversations from the serverDELETE/{orgName}/{appName}/users/{userName}/user_channelDeletes the conversation from the server.100/second

User attributes

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

NameMethodRequestDescriptionRate Limits
Setting user attributesPUT/{org_name}/{app_name}/metadata/user/{username}Sets the user attributes for the specified user.100/second
Retrieving user attributesGET/{org_name}/{app_name}/metadata/user/{username}Retrieves all the user attributes of the specified user.100/second
Retrieving the user attributes of multiple usersPOST/{org_name}/{app_name}/metadata/user/getRetrieves multiple users' attributes by specifying the user name list and user attribute list.100/second
Deleting user attributesDELETE/{org_name}/{app_name}/metadata/user/{username}Deletes all the user attributes for the specified user.100/second
Retrieving the total size of user attributesGET/{org_name}/{app_name}/metadata/user/capacityGets 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.

NameMethodRequestDescriptionRate Limits
Adding a contactPOST/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}Adds the specified user as a contact.100/second
Removing a contactDELETE/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}Removes the specified user from the contact list.100/second
Retrieving a contact listGET/{org_name}/{app_name}/users/{owner_username}/contacts/usersRetrieves the contact list.100/second
Retrieving a block listGET/{org_name}/{app_name}/users/{owner_username}/blocks/usersRetrieves the block list.50/second
Adding user to block listPOST/{org_name}/{app_name}/users/{owner_username}/blocks/usersAdd the specified user to the block list.50/second
Removing user from block listDELETE/{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.

NameMethodRequestDescriptionRate Limits
Retrieving all chat groups in the app (Pagination)GET/{org_name}/{app_name}/chatgroupsRetrieves the information of all the groups in the app.100/second
Retrieving all the chat groups the user joinsGET/{app_name}/users/{username}/joined_chatgroupsRetrieves all the groups the user joins by specifying the user name.50/second
Retrieving chat group detailsGET/{org_name}/{app_name}/chatgroups/{group_ids}Retrieves group details by specifying the group ID.100/second
Creating a chat groupPOST/{org_name}/{app_name}/chatgroupsCreates a chat group.100/second
Modifying chat group informationPUT/{org_name}/{app_name}/chatgroups/{group_id}Modifies the group information.100/second
Deleting a chat groupDELETE/{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.

NameMethodRequestDescriptionRate Limits
Retrieving chat group member list (Pagination)GET/{org_name}/{app_name}/chatgroups/{group_id}/usersRetrieves the member list of the chat group by pagination.100/second
Adding a chat group memberPOST/{org_name}/{app_name}/chatgroups/{group_id}/users/{username}Adds a user to the group member list.100/second
Adding multiple group membersPOST/{org_name}/{app_name}/chatgroups/{chatgroupid}/usersAdds multiple users to the group member list.100/second
Removing a chat group memberDELETE/{org_name}/{app_name}/chatgroups/{group_id}/users/{username}Removes the specified user from the group member list.100/second
Removing multiple chat group membersDELETE/{org_name}/{app_name}/chatgroups/{group_id}/users/{usernames}Removes the specified users from the group member list.100/second
Retrieving chat group admin listGET/{org_name}/{app_name}/chatgroups/{group_id}/adminRetrieves the group admin list.100/second
Adding a chat group adminPOST/{org_name}/{app_name}/chatgroups/{group_id}/adminAdds the specified user to the group admin list.100/second
Removing a chat group adminDELETE/{org_name}/{app_name}/chatgroups/{group_id}/admin/{oldadmin}Removes the specified user from the group admin list.100/second
Transferring chat group ownershipPUT/{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.

NameMethodRequestDescriptionRate Limits
Retrieving all chat roomsGET/{org_name}/{app_name}/chatroomsRetrieves the information of all the chat rooms in the app.50/second
Retrieving chat rooms a user joinsGET/{org_name}/{app_name}/users/{username}/joined_chatroomsRetrieves the chat rooms that a user joins by specifying the username.50/second
Retrieving chat room detailsGET/{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 roomPOST/{org_name}/{app_name}/chatroomsCreates a new chat room.50/second
Modifying chat room informationPUT/{org_name}/{app_name}/chatrooms/{chatroom_id}Modifies the chat room information.100/second
Deleting a chat roomDELETE/{org_name}/{app_name}/chatrooms/{chatroom_id}Deletes a chat room.100/second

Chat room member management

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

NameMethodRequestDescriptionRate Limits
Retrieving chat room member list (Pagination)GET/{org_name}/{app_name}/chatrooms/{chatroom_id}/usersRetrieves the member list of the chat room by pagination.100/second
Adding a chat room memberPOST/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}Adds the specified user to the chat room member list.100/second
Adding multiple chat room membersPOST/{org_name}/{app_name}/chatrooms/{chatroomid}/usersAdds multiple specified users to the chat room member list.100/second
Removing a chat room memberDELETE/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}Removes the specified user from the chat room member list.100/second
Removing multiple chat room membersDELETE/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}Removes the specified users from the chat room member list.100/second
Retrieving chat room admin listGET/{org_name}/{app_name}/chatrooms/{chatroom_id}/adminRetrieves the chat room admin list.100/second
Adding a chat room adminPOST/{org_name}/{app_name}/chatrooms/{chatroom_id}/adminAdds the specified user to the chat room admin list.100/second
Removing a chat room adminDELETE/{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.

NameMethodRequestDescriptionRate Limits
Globally mute a specified userPOST/{orgName}/{appName}/mutesMutes a specified user in one-to-one chats, chat groups, or chat rooms.100/second
Query the detailed information of global-muteGET/{orgName}/{appName}/mutes/usernameQueries 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 usersGET/{orgName}/{appName}/mutesRetrieves 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.

NameMethodRequestDescriptionRate Limits
Create a reactionPOST/{org_name}/{app_name}/reaction/user/{userId}Creates or adds a reaction to a specified message.100/second
Retrieve reactions with message IDsGET/{org_name}/{app_name}/reaction/user/{userId}Retrieves the information of the reaction according to the message ID.100/second
Delete a reactionDELETE/{org_name}/{app_name}/reaction/user/{userId}Deletes a reaction.100/second
Retrieve the detailed information of the reactionGET/{org_name}/{app_name}/reaction/user/{userId}/detailRetrieves 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:


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

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.