Message management

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

Before calling the following methods, make sure you understand the call frequency limit of the Chat RESTful APIs as described in Limitations.

Common parameters

The following table lists common request and response parameters of the Chat RESTful APIs:

Request parameters

Response parameters

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:

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.

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

This method sends a message to a peer user.

HTTP request

POST https://{host}/app-id/{app_id}/messages/users

Path parameter

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

Request header

Request body

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

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

Response body

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

For the other parameters and descriptions, see Common parameters.

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

Example

Request example

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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

• Send a text message

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

HTTP request

POST https://{host}/app-id/{app_id}/messages/chatgroups

Path parameter

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

Request header

Request body

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

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

HTTP response

Response body

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

For the other parameters and descriptions, see Common parameters.

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

Example

Request example

• Send a text message to all members in a chat group whether they are online or not

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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

• Send a text message

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

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

POST https://{host}/app-id/{app_id}/messages/chatrooms

Path parameter

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

Request header

Request body

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

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

HTTP response

Response body

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

For the other parameters and descriptions, see Common parameters.

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

Example

Request example

• Send a text message to members in a chat room

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

• Send a text message

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

  {
      "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

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

POST https://{host}/app-id/{app_id}/messages/chatrooms/broadcast

Path parameter

For the descriptions of path parameters, see Common Parameters.

Request header

Request body

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

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.

HTTP response

Response body

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:

For the other parameters and descriptions, see Common parameters.

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

Example

Request example

• Send a text broadcast message

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

  # 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

{
  "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

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

POST https://{host}/app-id/{app_id}/chatfiles

Path parameter

For the parameters and detailed descriptions, see Common parameters.

Request header

Request body

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

HTTP response

Response body

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

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

# 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

{
    "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

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

GET https://{host}/app-id/{app_id}/chatfiles/{file_uuid}

Path parameter

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

Request header

HTTP response

Response body

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

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

Example

Request example

# 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

{
    // The content of the voice/image file
}

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.

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

HTTP request

GET https://{host}/app-id/{app_id}/chatfiles/{file_uuid}

Path parameter

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

Request header

HTTP response

Response body

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

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

Example

Request example

# 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

{
    // The content of the thumbnail
}

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.

For each App Key, the call frequency limit of this method is 10 per minute.

HTTP request

GET https://{host}/app-id/{app_id}/chatmessages/${time}

Path parameter

For other parameters and detailed descriptions, see Common parameters.

Request header

HTTP response

Response body

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

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

# 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

{
    "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

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:

{
    "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:

  {
      "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 method.
  size	Number	The size of the image, in pixels.height: The image heightwidth: The image width
  type	String	The message type. For image messages, set it as img.
  url	String	The URL address of the image.

  Example:

  {
      "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:

  {
      "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 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:

  {
      "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 method.
  length	Number	The video duration, in seconds.
  size	Number	The video thumbnail size, in pixels.width: The width of the video thumbnailheight: The height of the video thumbnail
  thumb	String	The URL address of the video thumbnail.
  thumb_secret	String	The thumbnail file access key. This field exists if you set the access restriction when calling the upload-file method.
  type	String	The message type. For video messages, set it as video.
  url	String	The URL address of the video file. You can visit this URL to download video files.

  Example:

  {
      "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 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:

  {
      "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:

  {
      "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:

  {
      "bodies": [
          {
              "customExts": {
                  "name": "flower",
                  "size": "16",
                  "price": "100"
              },
              "customEvent": "gift_1",
              "type": "custom"
          }
      ]
  }

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

PUT https://{host}/app-id/{app_id}/messages/rewrite/{msg_id}

Path parameter

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

Request header

Request body

HTTP response

Response body

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

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. Common errors are shown in the following table:

Example

Request example

• Modify a sent text message:

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

  # 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

{
  "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

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.

POST https://{host}/app-id/{app_id}/messages/msg_recall

Path parameter

For the parameters and detailed descriptions, see Common parameters.

Request header

HTTP request

Request body

HTTP response

Response body

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

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

# 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

• If the message is recalled:

  {
      "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:

  {
      "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

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

DELETE https://{host}/app-id/{app_id}/users/{userName}/user_channel

Path parameter

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

Request header

Request body

HTTP response

Response body

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

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

Example

Request example

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

{
    "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

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

PUT https://{host}/app-id/{app_id}/messages/rewrite/{msg_id}

Path parameter

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

Request header

Request body

HTTP response

Response body

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

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. Common errors are shown in the following table:

For other exceptions, you can refer to Status codes for possible causes.

Example

Request example

• Modify a sent text message:

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

# 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

{
  "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

This method imports a one-to-one message. You can import only one message each time.

HTTP request

POST https://{host}/app-id/{app_id}/messages/users/import

Request header

Request body

HTTP Response

Response body

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

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

• Import a text message

  # 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

  # 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

{
    "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

This method imports a chat group message. You can import only one message each time.

HTTP request

POST https://{host}/app-id/{app_id}/messages/chatgroups/import

Request header

Request body

HTTP Response

Response body

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

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

• Import a text message

  # 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

  # 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

{
    "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

For details, see HTTP Status Codes.