Message management

This page shows how to call Chat RESTful APIs to send different types of messages, upload and download files, and retrieve historical messages.

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:

​

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

​

Parameter	Type	Description
action	String	The request method.
organization	String	The unique identifier assigned to each company (organization) by the Chat service. This is the same as org_name.
application	String	A unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter.
applicationName	String	The unique identifier assigned to each app by the Chat service . This is the same as app_name.
uri	String	The request URI.
path	String	The request path, which is part of the request URL. You can safely ignore this parameter.
entities	JSON	The response entity.
timestamp	Number	The Unix timestamp (ms) of the HTTP response.
duration	Number	The duration (ms) from when the HTTP request is sent to the time the response is received.

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

This group of methods enable you to send and receive peer-to-peer and group messages. Message types include text, image, voice, video, command, extension, file, and custom messages.

For each App Key, the call frequency limit of this method is 100 per second.

Follow the instructions below to implement sending messages:

• For text, command, and custom messages: Call the send-message method, and pass in the message content in the request body.
• For image, voice, video, and file messages:
  1. Call the upload-file method to upload images, voice messages, videos, or other types of files, and get the file file_uuid from the response body.
  2. Call the send-message method, and pass the file_uuid in the request body.

• When calling the RESTful APIs to send a message, you can use the from field to specify the message sender.
• If the data length of the request body exceeds 5 KB, error code 413 will be returned. The maximum data length of the request body and extension fields is 3 KB.

This method sends a message to a peer user.

_1

POST https://{host}/{org_name}/{app_name}/messages/users

For the descriptions of the path parameter, see Common Parameters.

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Accept	String	The content type. Set it to application/json.	Yes
Authorization	String	The authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.	Yes

The request body is a JSON object, which contains the following parameters:

Parameter	Type	Description	Required
from	String	The username of the message sender. If you do not set this field, the Chat server takes the admin as the sender. If you set it as the empty string "", this request fails.	No
to	Array	An array of the usernames of the message recipients. For each request, you can send a message to a maximum of 600 users. Within one minute, you can send messages to a maximum of 6,000 users.	Yes
type	String	The message type: txt: Text message img: Image message audio: Voice message video: Video message file: File message loc: Location message cmd: Command message custom: Custom message	Yes
body	JSON	The message content. For different message types, this parameter contains different fields. For details, see Body of different message types.	Yes
sync_device	Bool	Whether to synchronize the message to the message sender. true: Yes. false: No.	No
routetype	String	The route type when the message is not online. To send the message only when the user is online, set this parameter as ROUTE_TYPE. To send the message regardless of whether the user is online or not, do not set this parameter.	No
ext	JSON	The extension filed of the message.	No

Body of different message types

• Text message

  Parameter	Type	Description	Required
  msg	String	The message content.	Yes

• Image message

  Parameter	Type	Description	Required
  filename	String	The name of the image file.	Yes
  secret	String	The secret for accessing the image file. You can obtain the value of secret from the share-secret parameter in the response body of the upload method. If you set resctrict-access as true in the request header of upload when uploading the image file, ensure that you set this parameter.	No
  size	JSON	The size of the image (in pixels). This parameter contains two fields: height: The image height. width: The image width.	Yes
  url	String	The URL address of the image file, in the format of https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}, in which file_uuid can be obtained from the response body of upload after you upload the file to the server.	Yes

• Voice message

  Parameter	Type	Description	Required
  filename	String	The name of the audio file.	Yes
  secret	String	The secret for accessing the audio file. You can obtain the value of secret from the share-secret parameter in the response body of the upload method. If you set resctrict-access as true in the request header of upload when uploading the audio file, ensure that you set this parameter.	No
  length	Int	The length of the audio file (in seconds).	Yes
  url	String	The URL address of the audio file, in the format of https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}, in which file_uuid can be obtained from the response body of upload after you upload the file to the server.	Yes

• Video message

  Parameter	Type	Description	Required
  thumbnail	String	The URL address of the video thumbnail, in the format of https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}, in which file_uuid can be obtained from the response body of upload after you upload the file to the server.	Yes
  length	Int	The length of the video file (in seconds).	Yes
  secret	String	The secret for accessing the video file. You can obtain the value of secret from the share-secret parameter in the response body of the upload method. If you set resctrict-access as true in the request header of upload when uploading the video file, ensure that you set this parameter.	No
  file_length	Long	The data length of the video file (in bytes).	Yes
  thumb_secret	String	The secret for accessing the video thumbnail. You can obtain the value of thumb_secret from the share-secret parameter in the response body of the upload method. If you set restrict-access as true in the request header of upload when uploading the thumbnail, ensure that you set this parameter.	No
  url	String	The URL address of the video file, in the format of https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}, in which file_uuid can be obtained from the response body of upload after you upload the file to the server.	Yes

• File message

  Parameter	Type	Description	Required
  filename	String	The name of the file.	Yes
  secret	String	The secret for accessing the file. You can obtain the value of secret from the share-secret parameter in the response body of the upload method. If you set restrict-access as true in the request header of upload when uploading file, ensure that you set this parameter.	No
  url	String	The URL address of the file, in the format of https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}, in which file_uuid can be obtained from the response body of upload after you upload the file to the server.	Yes

• Location message

  Parameter	Type	Description	Required
  lat	String	The latitude of the location (in degrees).	Yes
  lng	String	The longitude of the location (in degrees).	Yes
  addr	String	The address of the location.	Yes

• CMD message

  Parameter	Type	Description	Required
  action	String	The content of the command.	Yes

• Custom message

  Parameter	Type	Description	Required
  customEvent	String	The event type customized by the user. The value of this parameter should be a regular expression, for example, [a-zA-Z0-9-_/\.]{1,32}.	No
  customExts	JSON	The event attribute customized by the user. The data type is Map<String,String>. You can set a maximum of 16 elements.	No
  from	String	The username of the message sender. If you do not set this field, the Chat server takes the admin as the sender. If you set it as the empty string "", this request fails.	No
  ext	JSON	The extension property, which supports customized settings of the app. Do not set it as ext:null.	No

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following parameters:

Parameter	Type	Description
data	JSON	The detailed content of the response. The value of this parameter includes a key-value pair where key represents the username of the message recipient and value the message ID. For example, if the returned data is "user2":"1029457500870543736", it means that user2 has sent a message with the ID of 1029457500870543736.

For the other parameters and descriptions, see Common parameters.

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

• Send a text message to the specified user without synchronizing the message with the sender

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'http://XXXX/XXXX/XXXX/messages/users' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "txt","body": {"msg": "testmessages"}}'

  
  

• Send a text message to the online user while synchronizing the message with the sender

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'http://XXXX/XXXX/XXXX/messages/users' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "txt","body": {"msg": "testmessages"},"routetype":"ROUTE_ONLINE", "sync_device":true}'

  
  

• Send an image message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/users' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "img","body": {"filename":"testimg.jpg","secret":"VfXXXXNb_","url":"https://XXXX/XXXX/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252","size":{"width":480,"height":720}}}'

  
  

• Send a voice message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/users' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "audio","body": {"url": "https://XXXX/XXXX/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42","filename": "testaudio.amr","length": 10,"secret": "HfXXXXCjM"}}'

  
  

• Send a video message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/users' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "video","body": {"thumb" : "https://XXXX/XXXX/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97","length" : 0,"secret":"VfXXXXNb_","file_length" : 58103,"thumb_secret" : "ZyXXXX2I","url" : "https://XXXX/XXXX/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"}}'

  
  

• Send a file message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/users' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "file","body": {"filename":"test.txt","secret":"1-g0XXXXua","url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444"}}'

  
  

• Send a location message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i "https://XXXX/XXXX/XXXX/messages/users" -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "loc","body":{"lat": "39.966","lng":"116.322","addr":"North America"}}'

  
  

• Send a CMD message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i "https://XXXX/XXXX/XXXX/messages/users" -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization:Bearer {YourToken}" -d '{"from": "user1","to": ["user2"],"type": "cmd","body":{"action":"action1"}}'

  
  

• Send a text message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send an image message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a voice message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a video message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a file message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a location message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a CMD message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a custom message

  
  

  _13

  {

  _13

  "path": "/messages/users",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/users",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "user2": "1029457500870543736"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

_1

POST https://{host}/{org_name}/{app_name}/messages/chatgroups

For the descriptions of the path parameter, see Common Parameters.

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Accept	String	The content type. Set it to application/json.	Yes
Authorization	String	The authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.	Yes

The request body is a JSON object, which contains the following parameters:

Parameter	Type	Description	Required
to	Array	An array of the group IDs that receives the message. Within one second, you can send a maximum of 20 messages to a chat group, and for each request, you can send messages to a maximum of 3 chat groups.	Yes

The other parameters and descriptions are the same with those of Sending a one-to-one message method.

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following parameters:

Parameter	Type	Description
data	JSON	The detailed content of the response. The value of this parameter includes a key-value pair where key represents the group ID that receives the message and value the message ID. For example, if the returned data is "184524748161025": "1029544257947437432", it means that a message with the ID of 1029544257947437432 is sent in chat group 184524748161025.

For the other parameters and descriptions, see Common parameters.

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

• Send a text message to the specified chat group without synchronizing the message with the sender

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'http://XXXX/XXXX/XXXX/messages/chatgroups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "txt","body": {"msg": "testmessages"}}'

  
  

• Send a text message to online users in the specified chat group while synchronizing the message with the sender

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'http://XXXX/XXXX/XXXX/messages/chatgroups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "txt","body": {"msg": "testmessages"},"routetype":"ROUTE_ONLINE", "sync_device":true}'

  
  

• Send an image message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "img","body": {"filename":"testimg.jpg","secret":"VfXXXXNb_","url":"https://XXXX/XXXX/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252","size":{"width":480,"height":720}}}'

  
  

• Send a voice message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "audio","body": {"url": "https://XXXX/XXXX/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42","filename": "testaudio.amr","length": 10,"secret": "HfXXXXCjM"}}'

  
  

• Send a video message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "video","body": {"thumb" : "https://XXXX/XXXX/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97","length" : 0,"secret":"VfXXXXNb_","file_length" : 58103,"thumb_secret" : "ZyXXXX2I","url" : "https://XXXX/XXXX/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"}}'

  
  

• Send a file message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "file","body": {"filename":"test.txt","secret":"1-g0XXXXua","url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444"}}'

  
  

• Send a location message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatgroups" -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "loc","body":{"lat": "39.966","lng":"116.322","addr":"North America"}}'

  
  

• Send a CMD message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatgroups" -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization:Bearer {YourToken}" -d '{"from": "user1","to": ["184524748161025"],"type": "cmd","body":{"action":"action1"}}'

  
  

• Send a text message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send an image message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a voice message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a video message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a file message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a location message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a CMD message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a custom message

  
  

  _13

  {

  _13

  "path": "/messages/chatgroups",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "184524748161025": "1029544257947437432"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

_1

POST https://{host}/{org_name}/{app_name}/messages/chatrooms

For the descriptions of the path parameter, see Common Parameters.

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Accept	String	The content type. Set it to application/json.	Yes
Authorization	String	The authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.	Yes

The request body is a JSON object, which contains the following parameters:

Parameter	Type	Description	Required
to	Array	An array of the chat room IDs that receives the message. Within one second, you can send messages to a maximum of 100 chat rooms, and for each request, you can send messages to a maximum of 10 chat rooms.	Yes

The other parameters and descriptions are the same with those of Sending a one-to-one message method.

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following parameters:

Parameter	Type	Description
data	JSON	The detailed content of the response. The value of this parameter includes a key-value pair where key represents the chat room ID that receives the message and value the message ID. For example, if the returned data is "185145305923585": "1029545553039460728", it means that a message with the ID of 1029545553039460728 is sent in chat room 185145305923585.

For the other parameters and descriptions, see Common parameters.

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

• Send a text message to the specified chat room without synchronizing the message with the sender

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'http://XXXX/XXXX/XXXX/messages/chatrooms' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "txt","body": {"msg": "testmessages"}}'

  
  

• Send a text message to online users in the specified chat room while synchronizing the message with the sender

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'http://XXXX/XXXX/XXXX/messages/chatrooms' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "txt","body": {"msg": "testmessages"},"routetype":"ROUTE_ONLINE", "sync_device":true}'

  
  

• Send an image message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatrooms' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "img","body": {"filename":"testimg.jpg","secret":"VfXXXXNb_","url":"https://XXXX/XXXX/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252","size":{"width":480,"height":720}}}'

  
  

• Send a voice message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatrooms' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "audio","body": {"url": "https://XXXX/XXXX/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42","filename": "testaudio.amr","length": 10,"secret": "HfXXXXCjM"}}'

  
  

• Send a video message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatrooms' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "video","body": {"thumb" : "https://XXXX/XXXX/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97","length" : 0,"secret":"VfXXXXNb_","file_length" : 58103,"thumb_secret" : "ZyXXXX2I","url" : "https://XXXX/XXXX/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"}}'

  
  

• Send a file message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatrooms' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "file","body": {"filename":"test.txt","secret":"1-g0XXXXua","url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444"}}'

  
  

• Send a location message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatrooms" -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "loc","body":{"lat": "39.966","lng":"116.322","addr":"North America"}}'

  
  

• Send a CMD message

  
  

  _2

  # Replace {YourToken} with the app token generated on your server

  _2

  curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatrooms" -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization:Bearer {YourToken}" -d '{"from": "user1","to": ["185145305923585"],"type": "cmd","body":{"action":"action1"}}'

  
  

• Send a text message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Sned an image message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a voice message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a video message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a file message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a location message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a CMD message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

• Send a custom message

  
  

  _13

  {

  _13

  "path": "/messages/chatrooms",

  _13

  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms",

  _13

  "timestamp": 1657254052191,

  _13

  "organization": "XXXX",

  _13

  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",

  _13

  "action": "post",

  _13

  "data": {

  _13

  "185145305923585": "1029545553039460728"

  _13

  },

  _13

  "duration": 0,

  _13

  "applicationName": "XXXX"

  _13

  }

  
  

This method enables you to upload images, audios, videos, or other types of files. For images and videos that have thumbnails, note the following:

• Images: After uploading an image, the Agora server automatically generates the thumbnail of the image.
• Videos: The Agora server does not generate thumbnails for videos automatically. After uploading a video, you must recall this method to upload the thumbnail for the video yourself.

File size	Thumbnail size
≤10	The size of the thumbnail remains the same as that of the original file.
>10	A thumbnail is generated based on the specified thumbnail-height and thumbnail-width parameters.
	If you leave thumbnail-height and thumbnail-width empty, the height and width of the thumbnail is 170 × 170 pixels by default.

Take note of the following considerations before calling this method:

• You cannot upload a file larger than 10 MB.
• You can restrict access to the uploaded file by requiring users to provide an access key before they can download the file. The format of the key is {{url}}?share-secret={{secret}}.

For each App Key, the call frequency limit of this method is 100 per second.

_1

POST https://{host}/{org_name}/{app_name}/chatfiles

For the parameters and detailed descriptions, see Common parameters.

Parameter	Type	Description	Required
Content-Type	String	The content type. Pass multipart/form-data	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
restrict-access	Bool	Whether to restrict access to this file. true: Restrict access to the file. The user needs to provide a file access key (share-secret) to download the file. You can obtain the access key from the response body. false: The access is not restricted. Users can download the file directly.	No

The request body is in the form-data format and contains the following fields:

Field	Type	Description	Required
file	String	The local path of the file to be uploaded.	Yes
thumbnail-height	Number	The height of the image thumbnail, in pixels. This parameter is valid only if the size of the uploaded image exceeds 10 KB. If you leave this parameter empty, the height is 170 pixels by default.	No
thumbnail-width	Number	The width of the image thumbnail, in pixels. This parameter is valid only if the size of the uploaded image exceeds 10 KB. If you leave this parameter empty, the width is 170 pixels by default.	No

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Field	Type	Description
entities.uuid	String	The file ID, a unique ID assigned to the file by the Chat service. You need to save this uuid yourself, and provide it when calling the Send-file-messages method.
entities.type	String	File type: chatfile.
entities.share-secret	String	The file access key. You need to save the share-secret yourself for use when downloading the file.

For other fields and 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.

_2

# Replace {YourToken} with the app token generated on your server, and the path of file with the local full path where the file to be uploaded is located

_2

curl -X POST https://XXXX/XXXX/XXXX/chatfiles -H 'Authorization: Bearer {YourToken}' -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' -H 'restrict-access: true' -F file=@/Users/test/9.2/chat/image/IMG_2953.JPG

_17

{

_17

"action": "post",

_17

"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",

_17

"path": "/chatfiles",

_17

"uri": "https://XXXX/XXXX/XXXX/chatfiles",

_17

"entities": [

_17

{

_17

"uuid": "5fd74830-XXXX-XXXX-822a-81ea50bb049d",

_17

"type": "chatfile",

_17

"share-secret": "X9dXXXX7Yc"

_17

}

_17

],

_17

"timestamp": 1554371126338,

_17

"duration": 0,

_17

"organization": "XXXX",

_17

"applicationName": "XXXX"

_17

}

This method downloads images, audio, video, or other types of files.

For each App Key, the call frequency limit of this method is 100 per second.

_1

GET https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}

Parameter	Type	Required	Description
file_uuid	String	Yes	The UUID of the file to be downloaded.

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

Parameter	Type	Description	Required
Accept	String	The content type. Set it toapplication/octet-stream, which means to download files in binary data stream format.	Yes
Authorization	String	The authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.	Yes
share-secret	String	The file access key for downloading the file. After the file is uploaded successfully using the Upload the file method, you can obtain the access key from the response body of upload.	This field is mandatory if you set restrict-access to true when uploading the file.

If the returned HTTP status code is 200, the request succeeds. You can refer to Common parameters for the parameters and detailed description.

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

_2

# Replace {YourToken} with the app token generated on your server, and the path of file with the local full path where the file to be downloaded is located

_2

curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer {YourToken}' -H 'share-secret: f0Vr-uyyEeiHpHmsu53XXXXXXXXZYgyLkdfsZ4xo2Z0cSBnB' 'http://XXXX/XXXX/XXXX/chatfiles/7f456bf0-XXXX-XXXX-b630-777db304f26c'-o /Users/test/chat/image/image.JPG

_3

{

_3

// The content of the voice/image file

_3

}

When uploading an image or video file, the Chat server can create a thumbnail for the file. This method has an extra thumbnail field in the request header compared with downloading a file.

For each App Key, the call frequency limit of this method is 100 per second.

_1

GET https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}

Parameter	Type	Required	Description
file_uuid	String	Yes	The UUID that the server generates for the thumbnail.

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

Parameter	Type	Description	Required
Accept	String	application/octet-stream, which means to download files in binary data stream format.	Yes
Authorization	String	Bearer ${YourAppToken}	Yes
thumbnail	Bool	Whether to download the thumbnail of the image or video file. true: Yes. false: (Default) No. Download the original file instead.	No.

If the returned HTTP status code is 200, the request succeeds. You can refer to Common parameters for the parameters and detailed description.

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

_2

# Replace {YourToken} with the app token generated on your server

_2

curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer {YourToken}' -H 'share-secret: f0Vr-uyyEeiHpHmsu53XXXXXXXXZYgyLkdfsZ4xo2Z0cSBnB' -H 'thumbnail: true' 'http://XXXX/XXXX/XXXX/chatfiles/7f456bf0-ecb2-11e8-b630-777db304f26c'

_3

{

_3

// The content of the thumbnail

_3

}

This method retrieves historical messages sent and received by the user.

• For each request, you can retrieve all the historical messages sent and received within one hour from the specified time.
• The response of this method is not returned in real time.
• The default storage time of historical messages differs by plan version. For details, see package details.

For each App Key, the call frequency limit of this method is 100 per second.

_1

GET https://{host}/{org_name}/{app_name}/chatmessages/${time}

Parameter	Type	Description	Required
time	String	The start time of the historical messages to query. UTC time, using the ISO8601 standard, in the format yyyyMMddHH. For example, if time is 2018112717, it means to query historical messages from 17:00 on November 27, 2018 to 18:00 on November 27, 2018.	Yes

For other parameters and detailed descriptions, see Common parameters.

Parameter	Description	Required
Accept	String	The content type. Set it to application/json.
Authorization	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

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
url	String	The download address of the historical message file. This parameter is valid within a limited time duration. The Expires field indicates when the returned URL is valid. Once the URL expires, you need to call this method to get the URL again.

For other fields and 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.

_2

# Replace {YourToken} with the app token generated on your server.

_2

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' 'http://XXXX/XXXX/XXXX/chatmessages/2018112717'

_14

{

_14

"action": "get",

_14

"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",

_14

"uri": "'http://XXXX/XXXX/XXXX/chatmessages/2018112717",

_14

"data": [

_14

{

_14

"url": "http://XXXX?Expires=1543316122&OSSAccessKeyId=XXXX&Signature=XXXX"

_14

}

_14

],

_14

"timestamp": 1543314322601,

_14

"duration": 0,

_14

"organization": "XXXX",

_14

"applicationName": "testapp"

_14

}

After successfully querying historical messages, you can visit the URL to download the historical message file and view the specific content of the historical message.

Historical messages contain the following parameters in JSON format:

Parameter	Type	Description
msg_id	String	The message ID.
timestamp	Long	The UTC Unix timestamp when the message is sent, in miliseconds.
from	String	The username that sends the message.
to	String	The message recipient. For a one-to-one chat, this parameter indicates the peer user that receives the message. For a group chat, this parameter indicates the chat group ID.
chat_type	String	The chat type: chat: One-to-one chat. groupchat: Group chat. chatroom: Chat room.
payload	JSON	The content of the message, including message extensions and customzied message attributes.

_22

{

_22

"msg_id": "5I02W-XX-8278a",

_22

"timestamp": 1403099033211,

_22

"direction":"outgoing",

_22

"to": "XXXX",

_22

"from": "XXXX",

_22

"chat_type": "chat",

_22

"payload":

_22

{

_22

"bodies": [

_22

{

_22

// For different message types, the parameters differ

_22

}

_22

],

_22

"ext":

_22

{

_22

"key1": "value1", ...

_22

},

_22

"from":"XXXX",

_22

"to":"XXXX"

_22

}

_22

}

The fields of bodies for different message types vary:

• Text messages

  Field	Type	Description
  msg	String	The message content.
  type	String	The message type. For text messages, set it as txt.

  Example:

  
  

  _8

  {

  _8

  "bodies": [

  _8

  {

  _8

  "msg": "welcome to Agora!",

  _8

  "type": "txt"

  _8

  }

  _8

  ]

  _8

  }

  
  

• Image messages

  Field	Type	Description
  file_length	Number	The size of the image attachment, in bytes.
  file_name	String	The name of the image file.
  secret	String	The image file access key. This field exists if you set the access restriction when calling the upload-file method.
  size	Number	The size of the image, in pixels. height: The image height width: The image width
  type	String	The message type. For image messages, set it as img.
  url	String	The URL address of the image.

  Example:

  
  

  _15

  {

  _15

  "bodies": [

  _15

  {

  _15

  "file_length": 128827,

  _15

  "filename": "test1.jpg",

  _15

  "secret": "DRGM8OZrEeO1vaXXXXXXXXHBeKlIhDp0GCnFu54xOF3M6KLr",

  _15

  "size": {

  _15

  "height": 1325,

  _15

  "width": 746

  _15

  },

  _15

  "type": "img",

  _15

  "url": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/65e54a4a-XXXX-XXXX-b821-ebde7b50cc4b"

  _15

  }

  _15

  ]

  _15

  }

  
  

• Location messages

  Field	Type	Description
  addr	String	The descriptions of the location.
  lat	Number	The latitude of the location.
  lng	Number	The longitude of the location.
  type	String	The message type. For location messages, set it as loc.

  Example:

  
  

  _10

  {

  _10

  "bodies": [

  _10

  {

  _10

  "addr": "test",

  _10

  "lat": 39.9053,

  _10

  "lng": 116.36302,

  _10

  "type": "loc"

  _10

  }

  _10

  ]

  _10

  }

  
  

• Voice messages

  Field	Type	Description
  file_length	Number	The size of the audio file, in bytes.
  filename	String	The audio file name, including a suffix that indicates the the audio file format.
  secret	String	The audio file access key. This field exists if you set the access restriction when calling the upload-file method.
  length	Number	The duration of the audio file, in seconds.
  type	String	The message type. For voice messages, set it as audio.
  url	String	The URL address of the audio file.

  Example:

  
  

  _12

  {

  _12

  "bodies": [

  _12

  {

  _12

  "file_length": 6630,

  _12

  "filename": "test1.amr",

  _12

  "length": 10,

  _12

  "secret": "DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",

  _12

  "type": "audio",

  _12

  "url": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/0637e55a-XXXX-XXXX-ba23-51f25fd1215b"

  _12

  }

  _12

  ]

  _12

  }

  
  

• Video messages

  Field	Type	Description
  file_length	Number	The size of the video file, in bytes.
  filename	String	The video file name, including a suffix that indicates the video file format.
  secret	String	The video file access key. This field exists if you set the access restriction when calling the upload-file method.
  length	Number	The video duration, in seconds.
  size	Number	The video thumbnail size, in pixels. width: The width of the video thumbnail height: The height of the video thumbnail
  thumb	String	The URL address of the video thumbnail.
  thumb_secret	String	The thumbnail file access key. This field exists if you set the access restriction when calling the upload-file method.
  type	String	The message type. For video messages, set it as video.
  url	String	The URL address of the video file. You can visit this URL to download video files.

  Example:

  
  

  _18

  {

  _18

  "bodies": [

  _18

  {

  _18

  "file_length": 58103,

  _18

  "filename": "1418105136313.mp4",

  _18

  "length": 10,

  _18

  "secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",

  _18

  "size": {

  _18

  "height": 480,

  _18

  "width": 360

  _18

  },

  _18

  "thumb": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/67279b20-XXXX-XXXX-8eee-21d3334b3a97",

  _18

  "thumb_secret": "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",

  _18

  "type": "video",

  _18

  "url": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"

  _18

  }

  _18

  ]

  _18

  }

  
  

• File messages

  Field	Type	Descriptions
  file_length	Number	The file size, in bytes.
  filename	String	The file name, including a suffix that indicates the file format.
  secret	String	The file access key. This field exists if you set the access restriction when calling the upload-file method.
  type	String	The message type. For file messages, set it as file.
  url	String	The URL address of the file. You can visit this URL to download video files.

  Example:

  
  

  _11

  {

  _11

  "bodies": [

  _11

  {

  _11

  "file_length": 3279,

  _11

  "filename": "record.md",

  _11

  "secret": "2RNXCgeeEeeXXXX-XXXXbtZXJH4cgr2admVXn560He2PD3RX",

  _11

  "type": "file",

  _11

  "url": "https://XXXX/XXXX/XXXX/chatfiles/d9135700-XXXX-XXXX-b000-a7039876610f"

  _11

  }

  _11

  ]

  _11

  }

  
  

• CMD messages

  Field	Type	Description
  action	String	The request method.
  type	String	The message type. For command messages, set it as cmd.

  Example:

  
  

  _8

  {

  _8

  "bodies": [

  _8

  {

  _8

  "action": "run",

  _8

  "type": "cmd"

  _8

  }

  _8

  ]

  _8

  }

  
  

• Custom messages

  Field	Type	Description
  customExts	JSON	The custom extension properties. You can set the fields in the extension properties yourself.
  customEvent	String	The custom event type.
  type	String	The message type. For custom messages, set it as custom.

  Example:

  
  

  _13

  {

  _13

  "bodies": [

  _13

  {

  _13

  "customExts": {

  _13

  "name": "flower",

  _13

  "size": "16",

  _13

  "price": "100"

  _13

  },

  _13

  "customEvent": "gift_1",

  _13

  "type": "custom"

  _13

  }

  _13

  ]

  _13

  }

  
  

Once a message is sent, you can call this method to recall the message. The default time limit for recalling a message is two minutes. To adjust this limit, contact support@agora.io.

For each App Key, the call frequency limit of this method is 100 per second.

_1

POST https://{host}/{org_name}/{app_name}/messages/msg_recall

For the parameters and detailed descriptions, see Common parameters.

Parameter	Type	Required	Description
Accept	String	The content type. Set it to application/json.	Yes
Authorization	String	Yes	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.

Parameter	Type	Required	Description
msg_id	String	Yes	The ID of the recalled message.
to	String	No	The user, chat group, or chat room that receives the recalled message. You can specify a username, a chat group ID, or a chat room ID. Note: If the recalled message exceeds the message storage duration and no longer exists in the server, this message cannot be recalled on the server side. You can only recall the message on the receiver client instead.
chat_type	String	Yes	The type of the chat where the recalled message is located. chat: A one-on-one chat. group_chat: A chat group. chatroom: A chat room.
from	String	No	The user who recalls the message. By default, the recaller is the app admin. You can also specify another user as the recaller.
force	bool	Yes	Whether to force a recall if the recalled message exceeds the message storage duration and no longer exists in the server. true: Force the recall on the client that receives the message. false: The recall fails. The maximum message storage duration varies based on different pricing plans. For details, see Message storage duration.

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Description
msg_id	The ID of the recalled message.
recalled	Returns yes if the request is successful.
from	The user who recalls the message. By default, the recaller is the app admin.
to	The user, chat group, or chat room that receives the recalled message.
chattype	The type of the chat where the recalled message is located. chat: A one-on-one chat. group_chat: A chat group. chatroom: A chat room.

For other fields and detailed descriptions, see Common parameters.

If the request fails, refer to Status codes for possible reasons.

_10

# Replace {YourToken} with the app token generated on your server

_10

curl -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer {YourToken}"

_10

"http://XXXX/XXXX/XXXX/messages/msg_recall"

_10

-d '{

_10

"msg_id": "1028442084794698104",

_10

"to": "user2",

_10

"from": "user1",

_10

"chat_type": "chat",

_10

"force": true

_10

}'

• If the message is recalled:

  
  

  _17

  {

  _17

  "path": "/messages/msg_recall",

  _17

  "uri": "https://XXXX/XXXX/XXXX/messages/msg_recall",

  _17

  "timestamp": 1657529588473,

  _17

  "organization": "XXXX",

  _17

  "application": "09ebbf8b-XXXX-XXXX-XXXX-d47c3b38e434",

  _17

  "action": "post",

  _17

  "data": {

  _17

  "recalled": "yes",

  _17

  "chattype": "chat",

  _17

  "from": "XXXX",

  _17

  "to": "XXXX",

  _17

  "msg_id": "1028442084794698104"

  _17

  },

  _17

  "duration": 8,

  _17

  "applicationName": "XXXX"

  _17

  }

  
  

• If the message fails to be recalled:

  
  

  _8

  {

  _8

  "msgs":

  _8

  [

  _8

  { "msg_id":"673296835082717140",

  _8

  "recalled":"not_found msg"

  _8

  }

  _8

  ]

  _8

  }

  
  

  Possible causes for failing to recall the message include the following:

  • "can't find message to": Fails to find the recipient of the message.
  • "exceed call time limit": Exceeds the time limit for recalling a message.
  • "not_found msg": The message is recalled.
  • "internal error": An internal error occurs with the back-end service.

This method enables the chat user to delete conversations one way from the server. Once the conversation is deleted, this chat user can no longer retrieve the conversation from the server. Other chat users can still get the conversation from the server.

For each App Key, the call frequency limit of this method is 100 per second.

_1

DELETE https://{host}/{orgName}/{appName}/users/{userName}/user_channel

Parameter	Type	Description	Required
userName	String	The username whose conversation is to be deleted.	Yes

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

Parameter	Type	Required	Description
Authorization	String	Yes	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.

Parameter	Type	Required	Description
channel	String	Yes	The ID of the conversation that you want to delete.
type	String	Yes	The type of the chat. chat: A one-on-one chat. groupchat: A group chat.
delete_roam	Bool	Yes	Whether to delete the chat from the server: true: Yes. false: No.

If the returned HTTP status code is 200, the request succeeds. The response body contains the following fields:

Parameter	Description
result	Returns ok if the request is successful.

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

_2

# Replace {YourToken} with the app token generated on your server

_2

curl -X DELETE -H "Authorization: Bearer {YourToken}" "https://XXXX/XXXX/XXXX/users/u1/user_channel" -d '{"channel":"u2", "type":"chat"，"delete_roam": true}'

_14

{

_14

"path": "/users/user_channel",

_14

"uri": "https://a1.agora.com/agora-demo/test-app/users/u1/user_channel",

_14

"timestamp": 1638440544078,

_14

"organization": "agora-demo",

_14

"application": "c3624975-3d51-4b0a-9da2-ee91ed4c5a76",

_14

"entities": [],

_14

"action": "delete",

_14

"data": {

_14

"result": "ok"

_14

},

_14

"duration": 3,

_14

"applicationName": "test-app"

_14

}

This method imports one-to-one messages.

_1

POST https://{host}/{orgName}/{appName}/messages/users/import

Parameter	Type	Required	Description
Authorization	String	Yes	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.

Parameter	Type	Description	Required
from	String	The username of the message sender.	Yes
target	String	The username of the message recipient.	Yes
type	String	The message type: txt: Text message img: Image message audio: Voice message video: Video message file: File message loc: Location message cmd: Command message custom: Custom message	Yes
body	JSON	The message content. For different message types, this parameter contains different fields. For details, see Body of different message types.	Yes
is_ack_read	Bool	Whether to set the message as read. true: Yes. false: No.	No
msg_timestamp	Long	The timestamp for importing the messages, in milliseconds. If you leave this parameter empty, the server automatically sets it as the current time.	No
need_download	Bool	Whether to download the attachment and upload it to the server: true: Yes. false: (Default) No.	No

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Description
msg_id	The ID of the imported messages.

For other fields and detailed descriptions, see Common parameters.

If the request fails, refer to Status codes for possible reasons.

• Import a text message

  
  

  _11

  # Replace {YourToken} with the app token generated on your server

  _11

  curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/XXXX/XXXX/messages/users/import" -d '{

  _11

  "target": "username2",

  _11

  "type": "txt",

  _11

  "body": {

  _11

  "msg": "import message."

  _11

  },

  _11

  "from": "username1",

  _11

  "is_ack_read": true,

  _11

  "msg_timestamp": 1656906628428

  _11

  }'

  
  

• Import an image message

  
  

  _17

  # Replace {YourToken} with token generated on your server

  _17

  curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/XXXX/XXXX/messages/users/import" -d '{

  _17

  "target": "username2",

  _17

  "type": "img",

  _17

  "body": {

  _17

  "url": "<YourImageUrl>",

  _17

  "filename": "<ImageFileName>",

  _17

  "size": {

  _17

  "width": 1080,

  _17

  "height": 1920

  _17

  }

  _17

  },

  _17

  "from": "username1",

  _17

  "is_ack_read": true,

  _17

  "msg_timestamp": 1656906628428,

  _17

  "need_download": true

  _17

  }'

  
  

_14

{

_14

"path": "/messages/users/import",

_14

"uri": "https://XXXX/XXXX/XXXX/messages/users/import",

_14

"timestamp": 1638440544078,

_14

"organization": "XXXX",

_14

"application": "c3624975-XXXX-XXXX-9da2-ee91ed4c5a76",

_14

"entities": [],

_14

"action": "post",

_14

"data": {

_14

"msg_id": "10212123848595"

_14

},

_14

"duration": 3,

_14

"applicationName": "XXXX"

_14

}

_1

POST https://{host}/{orgName}/{appName}/messages/chatgroups/import

Parameter	Type	Required	Description
Authorization	String	Yes	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.

Parameter	Type	Description	Required
from	String	The username of the message sender.	Yes
target	String	The chat group ID that receives the message.	Yes
type	String	The message type: txt: Text message img: Image message audio: Voice message video: Video message file: File message loc: Location message cmd: Command message custom: Custom message	Yes
body	JSON	The message content. For different message types, this parameter contains different fields. For details, see Body of different message types.	Yes
is_ack_read	Bool	Whether to set the message as read. true: Yes. false: No.	No
msg_timestamp	Long	The timestamp for importing the messages, in milliseconds. If you leave this parameter empty, the server automatically sets it as the current time.	No
need_download	Bool	Whether to download the attachment and upload it to the server: true: Yes. false: (Default) No.	No

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Description
msg_id	The ID of the imported messages.

For other fields and detailed descriptions, see Common parameters.

If the request fails, refer to Status codes for possible reasons.

• Import a text message

  
  

  _11

  # Replace {YourToken} with the app token generated on your server

  _11

  curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/XXXX/XXXX/messages/chatgroups/import" -d '{

  _11

  "target": "username2",

  _11

  "type": "txt",

  _11

  "body": {

  _11

  "msg": "import message."

  _11

  },

  _11

  "from": "username1",

  _11

  "is_ack_read": true,

  _11

  "msg_timestamp": 1656906628428

  _11

  }'

  
  

• Import an image message

  
  

  _17

  # Replace {YourToken} with the app token generated on your server

  _17

  curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/XXXX/XXXX/messages/chatgroups/import" -d '{

  _17

  "target": "username2",

  _17

  "type": "img",

  _17

  "body": {

  _17

  "url": "<YourImageUrl>",

  _17

  "filename": "<ImageFileName>",

  _17

  "size": {

  _17

  "width": 1080,

  _17

  "height": 1920

  _17

  }

  _17

  },

  _17

  "from": "username1",

  _17

  "is_ack_read": true,

  _17

  "msg_timestamp": 1656906628428,

  _17

  "need_download": true

  _17

  }'

  
  

_14

{

_14

"path": "/messages/users/import",

_14

"uri": "https://XXXX/XXXX/XXXX/messages/chatgroups/import",

_14

"timestamp": 1638440544078,

_14

"organization": "XXXX",

_14

"application": "c3624975-XXXX-XXXX-9da2-ee91ed4c5a76",

_14

"entities": [],

_14

"action": "post",

_14

"data": {

_14

"msg_id": "10212123848595"

_14

},

_14

"duration": 3,

_14

"applicationName": "XXXX"

_14

}

For details, see HTTP Status Codes.