# Message management (/en/api-reference/api-ref/im/message-management)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
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](./limitations#call-limit-of-server-sides).
## Common parameters [#common-parameters]
The following table lists common request and response parameters of the Chat RESTful APIs:
### Request parameters [#request-parameters]
| 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](/en/realtime-media/im/get-started/enable#get-the-information-of-the-agora-chat-project). | Yes |
| `app_id` | String | The unique identifier automatically assigned to each project by Agora | 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)
* 10 numbers (0-9)
* "\_", "-", "."
Do not use any of the 26 uppercase English letters (A-Z). Ensure that each `username` under the same App ID is unique. Do not set this parameter as a UUID, email address, phone number, or other sensitive information.
| Yes |
### Response parameters [#response-parameters]
| Parameter | Type | Description |
| :---------------- | :----- | :--------------------------------------------------------------------------------------------------- |
| `action` | String | The request method. |
| `organization` | String | The unique identifier assigned to each company (organization) by the Chat service. |
| `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 . |
| `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. |
## Authorization [#authorization]
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:
```html
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](/en/realtime-media/im/build/secure-access-and-authentication/authentication).
## Send a message [#send-a-message]
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](#upload) 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.
The maximum data length of the request body and extension fields is 5 KB, or the error 413 will be returned.
### Send a one-to-one message [#send-a-one-to-one-message]
This method sends a message to a peer user.
#### HTTP request [#http-request]
```html
POST https://{host}/app-id/{app_id}/messages/users
```
##### Path parameter [#path-parameter]
For the descriptions of the path parameter, see [Common Parameters](#param).
##### Request header [#request-header]
| 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 |
##### Request body [#request-body]
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](#body). | Yes |
| `roam_ignore_users` | List | No | Which users cannot obtain such message when they pull messages from the server. A maximum of 20 users can be passed in each time. |
| `sync_device` | Bool | Whether to synchronize the message to the message sender. `true`: Yes. `false`: No. | No |
| `routetype` | String | Whether the message is delivered only when the recipient(s) is/are online: If this parameter is set to `ROUTE_TYPE`, the message is delivered only when the recipient(s) is/are online. In this case, the message is discarded if the recipient is offline.If you do not set this parameter, the message is delivered whether the recipients are online or not. If the recipient(s) is/are offline, the message will not be delivered until they get online. | No |
| `ext` | JSON | The extension field of the message. It cannot be `null`. | No |
| `ext.em_ignore_notification` | Bool | Whether to send a silent message: `true`: Yes (Default). `false`: No. Sending silent messages means that when the user is offline, Agora Chat will not push message notifications to the user's device through a third-party message push service. Therefore, users will not receive push notifications for messages. When the user goes online again, all messages sent from the offline period will be received. Unlike the Do Not Disturb mode which is set by the recipient to prevent notifications during a certain period, sending silent messages is set by the sender. | 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. You are advised to pass in this parameter, or there is no image name displayed on the client that receives the message. | No |
| `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](#upload) method. If you set `restrict-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. | No |
| `url` | String | The URL address of the image file, in the format of `https://{host}/app-id/{app_id}/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. You are advised to pass in this parameter, or there is no voice file name displayed on the client that receives the message. | No |
| `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](#upload) method. If you set `restrict-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). | No |
| `url` | String | The URL address of the audio file, in the format of `https://{host}/app-id/{app_id}/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 |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `filename` | String | The name of the video file. You are advised to pass in this parameter, or there is no video file name displayed on the client that receives the message. | No |
| `thumb` | String | The URL address of the video thumbnail, in the format of `https://{host}/app-id/{app_id}/chatfiles/{file_uuid}`, in which `file_uuid` can be obtained from the response body of `upload` after you upload the file to the server. | No |
| `length` | Int | The length of the video file (in seconds). | No |
| `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](#upload) method. If you set `restrict-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). | No |
| `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](#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}/app-id/{app_id}/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. You are advised to pass in this parameter, or there is no file name displayed on the client that receives the message. | 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](#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}/app-id/{app_id}/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 meet the restrictions placed by 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`. You can set a maximum of 16 elements. | No |
#### HTTP response [#http-response]
##### Response body [#response-body]
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](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible causes.
#### Example [#example]
##### Request example [#request-example]
* Send a text message to the specified user without synchronizing the message with the sender
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'http://XXXX/app-id/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"},"roam_ignore_users": [],"ext": {"em_ignore_notification": true}}'
```
* Send a text message to the online user while synchronizing the message with the sender
````bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'http://XXXX/app-id/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"},"ext": {"em_ignore_notification": true},"routetype":"ROUTE_ONLINE", "sync_device":true}' ```
````
* Send an image message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252","size":{"width":480,"height":720}}}'
```
* Send a voice message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42","filename": "testaudio.amr","length": 10,"secret": "HfXXXXCjM"}}'
```
* Send a video message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/XXXX/messages/users' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["user2"],"type": "video","body": {"filename":"testvideo.avi","thumb" : "https://XXXX/app-id/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97","length" : 0,"secret":"VfXXXXNb_","file_length" : 58103,"thumb_secret" : "ZyXXXX2I","url" : "https://XXXX/app-id/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"}}'
```
* Send a file message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/d7eXXXX7444"}}'
```
* Send a location message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/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
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/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 custom message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/XXXX/messages/users" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization:Bearer " \
-d '{
"from": "user1",
"to": ["user2"],
"type": "custom",
"body": {
"customEvent": "custom_event",
"customExts":{
"ext_key1":"ext_value1"
}
}
}'
```
##### Response example [#response-example]
* Send a text message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send an image message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a voice message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a video message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a file message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a location message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a CMD message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a custom message
```json
{
"path": "/messages/users",
"uri": "https://XXXX/app-id/XXXX/messages/users",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"user2": "1029457500870543736"
},
"duration": 0,
"applicationName": "XXXX"
}
```
### Send a group message [#send-a-group-message]
#### HTTP request [#http-request-1]
```html
POST https://{host}/app-id/{app_id}/messages/chatgroups
```
##### Path parameter [#path-parameter-1]
For the descriptions of the path parameter, see [Common Parameters](#param).
##### Request header [#request-header-1]
| 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 |
##### Request body [#request-body-1]
The request body is a JSON object, which contains the following parameters:
| Parameter | Type | Required | Description |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `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 |
| `need_group_ack` | Boolean | Whether read receipts are required after the message is sent: `true`: Yes.`false: No.` | No |
The other parameters and descriptions are the same with those of [Sending a one-to-one message method](#request).
#### HTTP response [#http-response-1]
##### Response body [#response-body-1]
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](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible causes.
#### Example [#example-1]
##### Request example [#request-example-1]
* Send a text message to all members in a chat group whether they are online or not
```bash
# Replace {YourAppToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/XXXX/messages/chatgroups'
-H 'Content-Type: application/json'
-H 'Accept: application/json'
-H 'Authorization: Bearer '
-d '{
"from": "user1",
"to": ["184524748161025"],
"type": "txt",
"need_group_ack": false,
"body": {
"msg": "testmessages"
},
"roam_ignore_users": [],
"ext": {
"em_ignore_notification": true
},
"routetype":"ROUTE_ONLINE"
}'
```
* Send a text message to online users in a chat group by setting `routetype` to `ROUTE_ONLINE`.
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/XXXX/messages/chatgroups'
-H 'Content-Type: application/json'
-H 'Accept: application/json'
-H 'Authorization: Bearer '
-d '{
"from": "user1",
"to": ["184524748161025"],
"type": "txt",
"need_group_ack": false,
"body": {
"msg": "testmessages"
},
"ext": {
"em_ignore_notification": true
},
"routetype":"ROUTE_ONLINE"
}'
```
* Send an image message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252","size":{"width":480,"height":720}}}'
```
* Send a voice message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42","filename": "testaudio.amr","length": 10,"secret": "HfXXXXCjM"}}'
```
* Send a video message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/XXXX/messages/chatgroups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["184524748161025"],"type": "video","body": {"filename" : "testvideo.avi","thumb" : "https://XXXX/app-id/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97","length" : 0,"secret":"VfXXXXNb_","file_length" : 58103,"thumb_secret" : "ZyXXXX2I","url" : "https://XXXX/app-id/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"}}'
```
* Send a file message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/d7eXXXX7444"}}'
```
* Send a location message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/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
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/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 Custom message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/XXXX/messages/chatgroups" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization:Bearer " \
-d '{
"from": "user1",
"to": ["184524748161025"],
"type": "custom",
"body": {
"customEvent": "custom_event",
"customExts":{
"ext_key1":"ext_value1"
}
}
}'
```
##### Response example [#response-example-1]
* Send a text message
```json
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send an image message
```json
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a voice message
```bash
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a video message
```bash
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a file message
```bash
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a location message
```bash
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a CMD message
```bash
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a custom message
```bash
{
"path": "/messages/chatgroups",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"184524748161025": "1029544257947437432"
},
"duration": 0,
"applicationName": "XXXX"
}
```
### Send a chat room message [#send-a-chat-room-message]
This RESTful API allows you to send a maximum of 100 messages to 10 chat rooms in total on each call. Assuming that you send two messages to 10 chat rooms, the server counts it as 20 messages.
You can set the priority of a certain message type or chat room member to high, normal, or low. In this case, when the server is overloaded, low-priority messages
can be dropped to reserve resources for the high-priority ones. This ensures that high-priority messages are sent first.
Note that this feature can increase the delivery reliability of high-priority messages, but cannot guarantee the deliveries.
Even high-priorities messages can be dropped when the server load goes too high.
#### HTTP request [#http-request-2]
```html
POST https://{host}/app-id/{app_id}/messages/chatrooms
```
##### Path parameter [#path-parameter-2]
For the descriptions of the path parameter, see [Common Parameters](#param).
##### Request header [#request-header-2]
| 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 |
##### Request body [#request-body-2]
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 |
| `chatroom_msg_level` | String | The chat room message priority: `high` (default), `normal`, or `low`. | No |
The other parameters and descriptions are the same with those of [Sending a one-to-one message method](#request).
#### HTTP response [#http-response-2]
##### Response body [#response-body-2]
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](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible causes.
#### Example [#example-2]
##### Request example [#request-example-2]
* Send a text message to members in a chat room
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'http://XXXX/app-id/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"},"roam_ignore_users": []}'
```
* Send an image message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252","size":{"width":480,"height":720}}}'
```
* Send a voice message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42","filename": "testaudio.amr","length": 10,"secret": "HfXXXXCjM"}}'
```
* Send a video message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/XXXX/messages/chatrooms' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' -d '{"from": "user1","to": ["185145305923585"],"type": "video","body": {"filename":"testvideo.avi","thumb" : "https://XXXX/app-id/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97","length" : 0,"secret":"VfXXXXNb_","file_length" : 58103,"thumb_secret" : "ZyXXXX2I","url" : "https://XXXX/app-id/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"}}'
```
* Send a file message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i 'https://XXXX/app-id/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/app-id/XXXX/chatfiles/d7eXXXX7444"}}'
```
* Send a location message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/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
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/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 custom message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -i "https://XXXX/app-id/XXXX/messages/chatrooms" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization:Bearer " \
-d '{
"from": "user1",
"to": ["185145305923585"],
"type": "custom",
"body": {
"customEvent": "custom_event",
"customExts":{
"ext_key1":"ext_value1"
}
}
}'
```
##### Response example [#response-example-2]
* Send a text message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send an image message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a voice message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a video message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a file message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a location message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a CMD message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
* Send a custom message
```json
{
"path": "/messages/chatrooms",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms",
"timestamp": 1657254052191,
"organization": "XXXX",
"application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
"action": "post",
"data": {
"185145305923585": "1029545553039460728"
},
"duration": 0,
"applicationName": "XXXX"
}
```
### Send a broadcast message to all chat rooms under an app [#send-a-broadcast-message-to-all-chat-rooms-under-an-app]
This API sends a broadcast message to all active chat rooms under an app. Here, *active* indicates those that contain at least one member and in which at least one message is sent. This API can send all types of message to active chat rooms.
This API is available only to Pro and Enterprise plans.
For each App Key, the call frequency limit of this method is 10 per minute and 100 per day.
#### HTTP request [#http-request-3]
```html
POST https://{host}/app-id/{app_id}/messages/chatrooms/broadcast
```
##### Path parameter [#path-parameter-3]
For the descriptions of path parameters, see [Common Parameters](#param).
##### Request header [#request-header-3]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | The content type. Set it to `application/json`. | Yes |
| `Authorization` | String | The authentication token of the app 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 |
##### Request body [#request-body-3]
The request body is a JSON object, which contains the following parameters:
| Parameter | Type | Description | Required |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `from` | String | The user ID 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 |
| `chatroom_msg_level` | String | The chat room message priority: `high` (default), `normal`, or `low`. | No |
| `msg` | String | The message body. | Yes |
| `msg.type` | String | The broadcast message type: `txt`: Text message`img`: Image message`audio`: Audio message`video`: Video message`file`: File message`loc`: Location message`cmd`: Command message`custom`: Custom message | Yes |
| `msg.msg` | String | The message content. For different message types, this parameter contains different fields. For details, see [Body of different message types](#body). | Yes |
| `ext` | JSON | The extension filed of the message. It cannot be `null`. Also, the offline push notification can contain custom extension fields. For details, see [custom displays](/en/realtime-media/im/build/notifications-and-event-handling/offline-push/overview#custom-displays) of offline push. | No |
For the request body, different types of message only differ in fields in `msg`. Except `type`, fields in `msg` in this request have the same meanings as those in `body` in the request body of an HTTP request of [sending a one-to-one message](#send-a-one-to-one-message).
#### HTTP response [#http-response-3]
##### Response body [#response-body-3]
For various types of broadcast messages, the HTTP responses contain the same fields.
If the returned HTTP status code is `200`, the request succeeds, and the response body contains the following parameters:
| Parameter | Type | Description |
| :-------- | :--- | :---------------- |
| `data.id` | JSON | The broadcast ID. |
For the other parameters and descriptions, see [Common parameters](#param).
If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](./http-status-codes) for possible causes.
#### Example [#example-3]
##### Request example [#request-example-3]
* Send a text broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "txt",
"msg": "send broadcast to all chatroom"
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
* Send an image broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "img",
"filename":"testimg.jpg",
"secret":"VfXXXXNb_",
"url":"https://XXXX/app-id/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252",
"size":{
"width":480,
"height":720
}
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
* Send a voice broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "audio",
"url": "https://XXXX/app-id/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42",
"filename": "testaudio.amr",
"length": 10,
"secret": "HfXXXXCjM"
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
* Send a video broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "video",
"thumb" : "https://XXXX/app-id/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",
"length" : 0,
"secret":"VfXXXXNb_",
"file_length" : 58103,
"thumb_secret" : "ZyXXXX2I",
"url" : "https://XXXX/app-id/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
* Send a file broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "file",
"filename":"test.txt",
"secret":"1-g0XXXXua",
"url":"https://XXXX/app-id/XXXX/chatfiles/d7eXXXX7444"
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
* Send a location broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "loc",
"lat": "39.966",
"lng":"116.322",
"addr":"California"
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
* Send a transparent broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "cmd",
"action":"action1"
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
* Send a custom broadcast message
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"msg": {
"type": "custom",
"customEvent": "custom_event",
},
"from": "admin",
"ext": {
"extKey": "extValue"
},
"chatroom_msg_level": "low"
}'
```
##### Response example [#response-example-3]
```json
{
"path": "/messages/chatrooms/broadcast",
"uri": "https://XXXX/app-id/XXXX/messages/chatrooms/broadcast",
"timestamp": 1699944653964,
"organization": "XXXX",
"application": "331d42e6-ad85-460f-b6b0-d1fb6fef9f12",
"action": "post",
"data": {
"id": 1173998498812376874
},
"duration": 1,
"applicationName": "wang"
}
```
## Upload a file [#upload-a-file]
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 sizeThumbnail size
≤10 MBThe size of the thumbnail remains the same as that of the original file.
10 MBA 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.
### HTTP request [#http-request-4]
```html
POST https://{host}/app-id/{app_id}/chatfiles
```
#### Path parameter [#path-parameter-4]
For the parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-4]
| 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 |
| `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 |
#### Request body [#request-body-4]
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 |
### HTTP response [#http-response-4]
#### Response body [#response-body-4]
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](#sendmessage) 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](#download). |
For other fields and detailed descriptions, see [Common parameters](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-4]
#### Request example [#request-example-4]
```bash
# Replace {YourAppToken} 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
curl -X POST 'https://XXXX/app-id/XXXX/chatfiles' -H 'Authorization: Bearer ' -H 'Content-Type: multipart/form-data; boundary=---WebKitFormBoundary7MA4YWxkTrZu0gW' -H 'restrict-access: true' -H 'thumbnail-height: 180' -H 'thumbnail-width: 180' -F 'file="@/Users/test/9.2/agora/image/IMG_2953.JPG"'
```
#### Response example [#response-example-4]
```json
{
"action": "post",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"path": "/chatfiles",
"uri": "https://XXXX/app-id/XXXX/chatfiles",
"entities": [
{
"uuid": "5fd74830-XXXX-XXXX-822a-81ea50bb049d",
"type": "chatfile",
"share-secret": "X9dXXXX7Yc"
}
],
"timestamp": 1554371126338,
"duration": 0,
"organization": "XXXX",
"applicationName": "XXXX"
}
```
## Download a file [#download-a-file]
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.
### HTTP request [#http-request-5]
```html
GET https://{host}/app-id/{app_id}/chatfiles/{file_uuid}
```
#### Path parameter [#path-parameter-5]
| 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](#param).
#### Request header [#request-header-5]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| `Accept` | String | The content type. Set it to`application/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](#upload) 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. |
### HTTP response [#http-response-5]
#### Response body [#response-body-5]
If the returned HTTP status code is `200`, the request succeeds. You can refer to [Common parameters](#param) for the parameters and detailed description.
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-5]
#### Request example [#request-example-5]
```bash
# 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
curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer {YourToken}' -H 'share-secret: f0Vr-uyyEeiHpHmsu53XXXXXXXXZYgyLkdfsZ4xo2Z0cSBnB' 'http://XXXX/app-id/XXXX/chatfiles/7f456bf0-XXXX-XXXX-b630-777db304f26c'-o /Users/test/chat/image/image.JPG
```
#### Response example [#response-example-5]
```json
{
// The content of the voice/image file
}
```
## Download a thumbnail [#download-a-thumbnail]
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](#download).
For each App Key, the call frequency limit of this method is 100 per second.
### HTTP request [#http-request-6]
```html
GET https://{host}/app-id/{app_id}/chatfiles/{file_uuid}
```
#### Path parameter [#path-parameter-6]
| 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](#param).
#### Request header [#request-header-6]
| 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 |
### HTTP response [#http-response-6]
#### Response body [#response-body-6]
If the returned HTTP status code is `200`, the request succeeds. You can refer to [Common parameters](#param) for the parameters and detailed description.
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-6]
#### Request example [#request-example-6]
```bash
# Replace {YourToken} with the app token generated on your server
curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer {YourToken}' -H 'share-secret: f0Vr-uyyEeiHpHmsu53XXXXXXXXZYgyLkdfsZ4xo2Z0cSBnB' -H 'thumbnail: true' 'http://XXXX/app-id/XXXX/chatfiles/7f456bf0-ecb2-11e8-b630-777db304f26c'
```
#### Response example [#response-example-6]
```json
{
// The content of the thumbnail
}
```
## Retrieve historical messages [#retrieve-historical-messages]
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.
* Messages cannot be retrieved in real time. For example, at 9 a.m., you can retrieve messages that are sent or received at 8 a.m.
* The default storage time of historical messages differs by plan version. For details, see [package details](./pricing-plan-details).
For each App Key, the call frequency limit of this method is 10 per minute.
### HTTP request [#http-request-7]
```html
GET https://{host}/app-id/{app_id}/chatmessages/${time}
```
#### Path parameter [#path-parameter-7]
| 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](#param).
#### Request header [#request-header-7]
| Parameter | Description | Required |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept` | The content type. Set it to `application/json`. | Yes |
| `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 |
### HTTP response [#http-response-7]
#### Response body [#response-body-7]
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](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-7]
#### Request example [#request-example-7]
```bash
# Replace {YourToken} with the app token generated on your server.
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourToken}' 'http://XXXX/app-id/XXXX/chatmessages/2018112717'
```
#### Response example [#response-example-7]
```json
{
"action": "get",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"uri": "'http://XXXX/app-id/XXXX/chatmessages/2018112717",
"data": [
{
"url": "http://XXXX?Expires=1543316122&OSSAccessKeyId=XXXX&Signature=XXXX"
}
],
"timestamp": 1543314322601,
"duration": 0,
"organization": "XXXX",
"applicationName": "testapp"
}
```
### Content of historical messages [#content-of-historical-messages]
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. |
```json
{
"msg_id": "5I02W-XX-8278a",
"timestamp": 1403099033211,
"direction":"outgoing",
"to": "XXXX",
"from": "XXXX",
"chat_type": "chat",
"payload":
{
"bodies": [
{
// For different message types, the parameters differ
}
],
"ext":
{
"key1": "value1", ...
},
"from":"XXXX",
"to":"XXXX"
}
}
```
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:
```json
{
"bodies": [
{
"msg": "welcome to Agora!",
"type": "txt"
}
]
}
```
* 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](#upload) 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:
```json
{
"bodies": [
{
"file_length": 128827,
"filename": "test1.jpg",
"secret": "DRGM8OZrEeO1vaXXXXXXXXHBeKlIhDp0GCnFu54xOF3M6KLr",
"size": {
"height": 1325,
"width": 746
},
"type": "img",
"url": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/65e54a4a-XXXX-XXXX-b821-ebde7b50cc4b"
}
]
}
```
* 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:
```json
{
"bodies": [
{
"addr": "test",
"lat": 39.9053,
"lng": 116.36302,
"type": "loc"
}
]
}
```
* 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 audio file format. |
| `secret` | String | The audio file access key. This field exists if you set the access restriction when calling the [upload-file](#upload) 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:
```json
{
"bodies": [
{
"file_length": 6630,
"filename": "test1.amr",
"length": 10,
"secret": "DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",
"type": "audio",
"url": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/0637e55a-XXXX-XXXX-ba23-51f25fd1215b"
}
]
}
```
* 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](#upload) 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](#upload) 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:
```json
{
"bodies": [
{
"file_length": 58103,
"filename": "1418105136313.mp4",
"length": 10,
"secret": "VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",
"size": {
"height": 480,
"width": 360
},
"thumb": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/67279b20-XXXX-XXXX-8eee-21d3334b3a97",
"thumb_secret": "ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",
"type": "video",
"url": "https://a1.agora.com/agora-demo/chatdemoui/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"
}
]
}
```
* 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](#upload) 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:
```json
{
"bodies": [
{
"file_length": 3279,
"filename": "record.md",
"secret": "2RNXCgeeEeeXXXX-XXXXbtZXJH4cgr2admVXn560He2PD3RX",
"type": "file",
"url": "https://XXXX/app-id/XXXX/chatfiles/d9135700-XXXX-XXXX-b000-a7039876610f"
}
]
}
```
* CMD messages
| Field | Type | Description |
| :------- | :----- | :------------------------------------------------------- |
| `action` | String | The request method. |
| `type` | String | The message type. For command messages, set it as `cmd`. |
Example:
```json
{
"bodies": [
{
"action": "run",
"type": "cmd"
}
]
}
```
* 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:
```json
{
"bodies": [
{
"customExts": {
"name": "flower",
"size": "16",
"price": "100"
},
"customEvent": "gift_1",
"type": "custom"
}
]
}
```
## Modify a text or custom message [#modify-a-text-or-custom-message]
You can call the RESTful API to edit a text or custom message that is successfully sent.
For each App Key, the call frequency limit of this method is 100 per second.
### HTTP request [#http-request-8]
```bash
PUT https://{host}/app-id/{app_id}/messages/rewrite/{msg_id}
```
#### Path parameter [#path-parameter-8]
| Parameter | Type | Description | Required |
| :-------- | :----- | :------------------------------------ | :------- |
| `msg_id` | String | The ID of the message to be modified. | Yes |
For the other parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-8]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | The parameter type. Set it as `application/json`. | Yes |
| `Accept` | String | The parameter type. Set it as `application/json`. | 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 |
#### Request body [#request-body-5]
| Parameter | Type | Description | Required |
| :-------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `user` | String | The user that modifies the message. | No |
| `new_msg` | JSON | The modified message. | Yes |
| `new_msg.type` | String | The type of message to modify: `txt`: The text message; `custom`: The custom message. | Yes |
| `new_msg.msg` | String | The modified message content. **This parameter is valid only for text messages.** | Yes |
| `new_msg.customEvent` | String | The event type customized by the user. The value of this parameter should meet restrictions placed by a regular expression, for example, \[a-zA-Z0-9-\_/.]\{1,32}. This parameter value can contain up to 32 characters. **This parameter is valid only for custom messages.** | No |
| `new_msg.customExts` | JSON | The event attribute customized by the user. The data type is `Map`. You can set a maximum of 16 elements. **This parameter is valid only for custom messages.** | No |
| `new_ext` | JSON | The modified message extension information. This parameter is valid only for custom messages. | No |
| `is_combine_ext` | Boolean | Whether the modified message extension information is merged with or replaces the original information:(Default)`true`: Merge; `false`: Replace. | No |
### HTTP response [#http-response-8]
#### Response body [#response-body-8]
If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:
| Parameter | Type | Description |
| :-------- | :----- | :----------------------------------------------------------------------- |
| `data` | String | The value `success` indicates that the message is successfully modified. |
For other fields and detailed descriptions, see [Common parameters](#param).
If the returned HTTP status code is not `200`, the request fails. Common errors are shown in the following table:
| Error | HTTP status code | Code explanation | Error description |
| :------------------------------------- | :--------------- | :------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UnsupportedMessageTypeException` | `400` | The message is of a type that is currently not supported for modification. | This type of message cannot be modified. Currently, only text messages and custom messages that are successful sent can be modified. |
| `InvalidMessageIdException` | `400` | The provided message ID is not a valid number. | The message ID can only contain digits. |
| `RewriteMessageNotAuthorizedException` | `401` | You are not authorized to edit this message. | The ID of the message to be modified does not belong to the current app. |
| `EditLimitExceededException` | `403` | The message has reached its edit limit and cannot be modified further. | The number of times the message is modified has reached the upper limit which is 10. |
| `EditFeatureNotEnabledException` | `403` | The edit message feature is not enabled for this user or system. | The message modification feature is not enabled. Before using this feature, you need to contact [support@agora.io](mailto\:support@agora.io) to enable it. |
| `MessageUnavailableException` | `404` | The message is unavailable or has expired. | The message to be modified does not exist or has been removed due to expiration. |
| `RewriteMessageInternalErrorException` | `500` | An unknown error occurred while processing the request. | The message modification fails due to an internal error. |
### Example [#example-8]
#### Request example [#request-example-8]
* Modify a sent text message:
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -X PUT -i 'https://XXXX/app-id/XXXX/messages/rewrite/1235807318835202004' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"user": "user1",
"new_msg": {
"type": "txt",
"msg": "update message content"
},
}'
```
* Modify a sent custom message:
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -X PUT -i 'https://XXXX/app-id/XXXX/messages/rewrite/1235807318835202004' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"user": "user1",
"new_msg": {
"type": "custom",
"customEvent": "custom_event",
"customExts":{
"ext_key1":"ext_value1"
}
},
"new_ext": {
"key": "value",
"old_key": "new_value"
},
"is_combine_ext": true
}'
```
#### Response example [#response-example-8]
```json
{
"path": "/messages/rewrite/1235807318835202004",
"uri": "https://XXXX/app-id/XXXX/messages/rewrite/1235807318835202004",
"timestamp": 1705372388118,
"organization": "XXXX",
"application": "ff678832-XXXX-XXXX-8130-58ac38cb6c15",
"action": "put",
"data": "success",
"duration": 49,
"applicationName": "XXXX"
}
```
## Recall a message [#recall-a-message]
Once a message is sent, you can call this API to recall it. This API recalls a message that is saved both locally and on the server, whether it is a historical message, offline message or a roaming message on the server, or a message in the memory or local database of the message sender or recipient. If an attachment message, like an image, voice, video, or file message, is recalled, the attachment of the message is also deleted.
The default time limit for recalling a message is two minutes. You can extend this time frame to up to 7 days in Agora Console. To do so, select a project that enables Agora Chat, then click **Configure** > **Features** > **Message recall**.
For each App Key, the call frequency limit of this method is 100 per second.
```html
POST https://{host}/app-id/{app_id}/messages/msg_recall
```
#### Path parameter [#path-parameter-9]
For the parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-9]
### HTTP request [#http-request-9]
| 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. |
#### Request body [#request-body-6]
| Parameter | Type | Required | Description |
| :------------ | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `msg_id` | String | Yes | The ID of the message to recall. As only one message can be recalled each time, you can pass in only one message ID. |
| `to` | String | Yes | The user, chat group, or chat room that receives the message to recall. You can specify a user ID, a chat group ID, or a chat room ID.
Note
If the message to recall no longer exists on the server, only the message on the recipient client is recalled.
|
| `chat_type` | String | Yes | The type of the chat where the message to recall is sent. `chat`: A one-on-one chat. `groupchat`: 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. |
| `sync_device` | Bool | No | Whether to synchronize the recall of a one-to-one message to all online devices of the message sender. (Default):* `true`: Yes
* `false`: No
When `force` is set to `true`, to recall a message that expires, you need to set `from` to the sender of the message.
|
| `force` | Bool | No | Whether to allow to recall messages forcibly: `true`: Yes. In this case, you can recall messages whether they expire. To recall the expired messages, you must set `force` to `true`. (Default) `false`: No. In this case, you can only recall messages that still exist on the server within the recall duration. |
### HTTP response [#http-response-9]
#### Response body [#response-body-9]
If the returned HTTP status code is `200`, the request succeeds, and the response body contains the following fields:
| Parameter | Type | Description |
| :--------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `msg_id` | String | The ID of the recalled message. |
| `recalled` | String | Returns `yes` if the request is successful. |
| `from` | String | The user who recalls the message. By default, the recaller is the app admin. |
| `to` | String | The user, chat group, or chat room that receives the recalled message. |
| `chattype` | String | 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](#param).
If the request fails, refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-9]
#### Request example [#request-example-9]
```bash
# Replace {YourToken} with the app token generated on your server
curl -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer {YourToken}"
"http://XXXX/app-id/XXXX/messages/msg_recall"
-d '{
"msg_id": "1028442084794698104",
"to": "user2",
"from": "user1",
"chat_type": "chat",
"force": true
}'
```
#### Response example [#response-example-9]
* If the message is recalled:
```json
{
"path": "/messages/msg_recall",
"uri": "https://XXXX/app-id/XXXX/messages/msg_recall",
"timestamp": 1657529588473,
"organization": "XXXX",
"application": "09ebbf8b-XXXX-XXXX-XXXX-d47c3b38e434",
"action": "post",
"data": {
"recalled": "yes",
"chattype": "chat",
"from": "XXXX",
"to": "XXXX",
"msg_id": "1028442084794698104"
},
"duration": 8,
"applicationName": "XXXX"
}
```
* If the message fails to be recalled:
```json
{
"msgs":
[
{ "msg_id":"673296835082717140",
"recalled":"not_found msg"
}
]
}
```
Possible causes for failing to recall the message include the following:
* `"can't find message to"`: The recipient of the message to recall is not found.
* `"exceed call time limit"`: The time limit for recalling a message is exceeded.
* `"not_found msg"`: The message is already recalled or no longer exists because its storage period expires.
* `"internal error"`: An internal error occurs with the back-end service.
## Delete conversations one way from the server [#delete-conversations-one-way-from-the-server]
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.
### HTTP request [#http-request-10]
```html
DELETE https://{host}/app-id/{app_id}/users/{userName}/user_channel
```
#### Path parameter [#path-parameter-10]
| 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](#param).
#### Request header [#request-header-10]
| 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. |
#### Request body [#request-body-7]
| 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. |
### HTTP response [#http-response-10]
#### Response body [#response-body-10]
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](./http-status-codes) for possible reasons.
### Example [#example-10]
#### Request example [#request-example-10]
```bash
curl -L -X DELETE 'https://XXXX/app-id/XXXX/users/u1/user_channel'
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '
{ "channel": "u2", "type": "chat", "delete_roam": true }
'
```
#### Response example [#response-example-10]
```json
{
"path": "/users/user_channel",
"uri": "https://a1.agora.com/agora-demo/test-app/users/u1/user_channel",
"timestamp": 1638440544078,
"organization": "agora-demo",
"application": "c3624975-3d51-4b0a-9da2-ee91ed4c5a76",
"entities": [],
"action": "delete",
"data": {
"result": "ok"
},
"duration": 3,
"applicationName": "test-app"
}
```
## Modify a text or custom message [#modify-a-text-or-custom-message-1]
You can call the RESTful API to modify a text or custom message that was successfully sent. For each App Key, the call frequency limit of this method is 100 per second.
### HTTP request [#http-request-11]
```html
PUT https://{host}/app-id/{app_id}/messages/rewrite/{msg_id}
```
#### Path parameter [#path-parameter-11]
| Parameter | Type | Description | Required |
| :-------- | :----- | :------------------------------------ | :------- |
| `msg_id` | String | The ID of the message to be modified. | Yes |
For the other parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-11]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | The parameter type. Set it as `application/json`. | Yes |
| `Accept` | String | The parameter type. Set it as `application/json`. | 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 |
#### Request body [#request-body-8]
| Parameter | Type | Description | Required |
| :-------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `user` | String | The user that modifies the message. | No |
| `new_msg` | JSON | The modified message. | Yes |
| `new_msg.type` | String | The type of message to modify: `txt`: The text message. `custom`: The custom message. | Yes |
| `new_msg.msg` | String | The modified message content. **This parameter is valid only for text messages.** | Yes |
| `new_msg.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}`. This parameter value can contain up to 32 characters. **This parameter is valid only for custom messages.** | No |
| `new_msg.customExts` | JSON | The event attribute customized by the user. The data type is `Map`. You can set a maximum of 16 elements. **This parameter is valid only for custom messages.** | No |
| `new_ext` | JSON | The modified message extension information. This parameter is valid only for custom messages. | No |
| `is_combine_ext` | Boolean | Whether the modified message extension information is merged with or replaces the original information:(Default)`true`: Merge. `false`: Replace. | No |
### HTTP response [#http-response-11]
#### Response body [#response-body-11]
If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:
| Parameter | Type | Description |
| :-------- | :----- | :----------------------------------------------------------------------- |
| `data` | String | The value `success` indicates that the message is successfully modified. |
For other fields and detailed descriptions, see [Common parameters](#param).
If the returned HTTP status code is not `200`, the request fails. Common errors are shown in the following table:
| Error | HTTP Status Code | Code Information | Error Description |
| :------------------------------------- | :--------------- | :------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UnsupportedMessageTypeException` | 400 | The message is of a type that is currently not supported for modification. | This type of message cannot be modified. Currently, only text messages and custom messages that are successful sent can be modified. |
| `InvalidMessageIdException` | 400 | The provided message ID is not a valid number. | The message ID can only contain digits. |
| `RewriteMessageNotAuthorizedException` | 401 | You are not authorized to edit this message. | The ID of the message to be modified does not belong to the current app. |
| `EditLimitExceededException` | 403 | The message has reached its edit limit and cannot be modified further. | The number of times the message is modified has reached the upper limit which is 10. |
| `EditFeatureNotEnabledException` | 403 | The edit message feature is not enabled for this user or system. | The message modification feature is not enabled. Before using this feature, you need to contact [support@agora.io](mailto\:support@agora.io) to enable it. |
| `MessageUnavailableException` | 404 | The message is unavailable or has expired. | The message to be modified does not exist or has been removed due to expiration. |
| `RewriteMessageInternalErrorException` | 500 | An unknown error occurred while processing the request. | The message modification fails due to an internal error. |
For other exceptions, you can refer to [Status codes](./http-status-codes) for possible causes.
### Example [#example-11]
#### Request example [#request-example-11]
* Modify a sent text message:
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -X PUT -i 'https://XXXX/app-id/XXXX/messages/rewrite/1235807318835202004' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"user": "user1",
"new_msg": {
"type": "txt",
"msg": "update message content"
},
}'
```
* Modify a sent custom message:
```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -X PUT -i 'https://XXXX/app-id/XXXX/messages/rewrite/1235807318835202004' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"user": "user1",
"new_msg": {
"type": "custom",
"customEvent": "custom_event",
"customExts":{
"ext_key1":"ext_value1"
}
},
"new_ext": {
"key": "value",
"old_key": "new_value"
},
"is_combine_ext": true
}'
```
#### Response example [#response-example-11]
```json
{
"path": "/messages/rewrite/1235807318835202004",
"uri": "https://XXXX/app-id/XXXX/messages/rewrite/1235807318835202004",
"timestamp": 1705372388118,
"organization": "XXXX",
"application": "ff678832-XXXX-XXXX-8130-58ac38cb6c15",
"action": "put",
"data": "success",
"duration": 49,
"applicationName": "XXXX"
}
```
## Import a one-to-one chat message [#import-a-one-to-one-chat-message]
This method imports a one-to-one message. You can import only one message each time.
### HTTP request [#http-request-12]
```html
POST https://{host}/app-id/{app_id}/messages/users/import
```
#### Request header [#request-header-12]
| 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. |
#### Request body [#request-body-9]
| 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](#body). | Yes |
| `ext` | JSON | The message extension field that allows you to add custom information in the format of key-value pairs. | No |
| `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. In this case, you need to make sure that the attachment URL is publicly accessible. `false`: (Default) No. | No |
### HTTP Response [#http-response-12]
#### Response body [#response-body-12]
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](#param).
If the request fails, refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-12]
#### Request example [#request-example-12]
* Import a text message
```bash
# Replace {YourToken} with the app token generated on your server
curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/app-id/XXXX/messages/users/import" -d '{
"target": "username2",
"type": "txt",
"body": {
"msg": "import message."
},
"ext": {
"key1": "value1"
},
"from": "username1",
"is_ack_read": true,
"msg_timestamp": 1656906628428
}'
```
* Import an image message
```bash
# Replace {YourToken} with token generated on your server
curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/app-id/XXXX/messages/users/import" -d '{
"target": "username2",
"type": "img",
"body": {
"url": "",
"filename": "",
"size": {
"width": 1080,
"height": 1920
}
},
"ext": {
"key1": "value1"
},
"from": "username1",
"is_ack_read": true,
"msg_timestamp": 1656906628428,
"need_download": true
}'
```
#### Response example [#response-example-12]
```json
{
"path": "/messages/users/import",
"uri": "https://XXXX/app-id/XXXX/messages/users/import",
"timestamp": 1638440544078,
"organization": "XXXX",
"application": "c3624975-XXXX-XXXX-9da2-ee91ed4c5a76",
"entities": [],
"action": "post",
"data": {
"msg_id": "10212123848595"
},
"duration": 3,
"applicationName": "XXXX"
}
```
## Import a chat group message [#import-a-chat-group-message]
This method imports a chat group message. You can import only one message each time.
### HTTP request [#http-request-13]
```html
POST https://{host}/app-id/{app_id}/messages/chatgroups/import
```
#### Request header [#request-header-13]
| 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. |
#### Request body [#request-body-10]
| 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](#body). | Yes |
| `ext` | JSON | The message extension field that allows you to add custom information in the format of key-value pairs. | No |
| `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. In this case, you need to make sure that the attachment URL is publicly accessible.`false`: (Default) No. | No |
### HTTP Response [#http-response-13]
#### Response body [#response-body-13]
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](#param).
If the request fails, refer to [Status codes](./http-status-codes) for possible reasons.
### Example [#example-13]
#### Request example [#request-example-13]
* Import a text message
```bash
# Replace {YourAppToken} with the app token generated on your server
curl -X POST -H "Authorization: Bearer " "https://XXXX/app-id/XXXX/messages/chatgroups/import" -d '{
"target": "1123376564212",
"type": "txt",
"body": {
"msg": "import message."
},
"ext": {
"key1": "value1"
},
"from": "username1",
"is_ack_read": true,
"msg_timestamp": 1656906628428
}'
```
* Import an image message
```bash
# Replace {YourAppToken} with the app token generated on your server
curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/app-id/XXXX/messages/chatgroups/import" -d '{
"target": "1123376564212",
"type": "img",
"body": {
"url": "",
"filename": "",
"size": {
"width": 1080,
"height": 1920
}
},
"ext": {
"key1": "value1"
},
"from": "username1",
"is_ack_read": true,
"msg_timestamp": 1656906628428,
"need_download": true
}'
```
#### Response example [#response-example-13]
```json
{
"path": "/messages/users/import",
"uri": "https://XXXX/app-id/XXXX/messages/chatgroups/import",
"timestamp": 1638440544078,
"organization": "XXXX",
"application": "c3624975-XXXX-XXXX-9da2-ee91ed4c5a76",
"entities": [],
"action": "post",
"data": {
"msg_id": "10212123848595"
},
"duration": 3,
"applicationName": "XXXX"
}
```
## Status codes [#status-codes]
For details, see [HTTP Status Codes](./http-status-codes).