diff --git a/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_message.md b/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_message.md index 317bfd90c91..92a98d8a61c 100644 --- a/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_message.md +++ b/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_message.md @@ -91,7 +91,7 @@ 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 recipient. For each request, you can send a message to a maximum of 600 users. Within one minute, you can send 6,000 messages. | Yes | +| `to` | Array | An array of the usernames of the message recipient. For each request, you can send a message to a maximum of 600 users. Within one minute, you can send 6,000 messages. The server does not check whether the usernames you passed in exist. If the usernames you passed in do not exist, the server still sends the message instead of displaying an error. | Yes | | `type` | String | The message type: | 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. | @@ -438,7 +438,7 @@ The request body is a JSON object, which contains the following parameters: | Parameter | Type | Description | Required | | --- | --- | --- | --- | -| `to` | Array | An array of the group IDs that receives the message. Within one second, you can send a maximum of 20 messages to a chat group, and for each request, you can send messages to a maximum of 3 chat groups. | Yes | +| `to` | Array | An array of the group IDs that receives the message. Within one second, you can send a maximum of 20 messages to chat groups, 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: | No | The other parameters and descriptions are the same with those of [Sending a one-to-one message method](#request). @@ -750,7 +750,7 @@ 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 | +| `to` | Array | An array of the chat room IDs that receive 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: | No | The other parameters and descriptions are the same with those of [Sending a one-to-one message method](#request). @@ -1303,7 +1303,7 @@ For the parameters and detailed descriptions, see [Common parameters](#param). | Parameter | Type | Description | Required | | :---------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `Content-Type` | String | The content type. Pass `multipart/form-data` | Yes | +| `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. | 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 | @@ -1412,6 +1412,8 @@ If the returned HTTP status code is not `200`, the request fails. You can refer curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer {YourToken}' -H 'share-secret: f0Vr-uyyEeiHpHmsu53XXXXXXXXZYgyLkdfsZ4xo2Z0cSBnB' 'http://XXXX/XXXX/XXXX/chatfiles/7f456bf0-XXXX-XXXX-b630-777db304f26c'-o /Users/test/chat/image/image.JPG ``` +Note that `/Users/test/easemob/image/image.JPG` is the local path to store the file. You need to replace the path with your own local file path, or the request fails. + #### Response example ```json @@ -1422,7 +1424,7 @@ curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer {You ## 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:true` field in the request header compared with [downloading a file](#download). +When receiving an image or video message, you can download the thumbnail of the image or video first, and then the original file as required. The only difference between downloading thumbnails and original files is that the former has an extra `thumbnail:true` field in the request header. When the server receives a request header containing this field, it returns the thumbnail, otherwise it returns the original file. For each App Key, the call frequency limit of this method is 100 per second. @@ -1449,6 +1451,7 @@ For the other parameters and detailed descriptions, see [Common parameters](#par | `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. | No. | +| `share-secret` | String | The file access key for downloading the thumbnail. After the thumbnail 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 @@ -1558,10 +1561,12 @@ The data format for historical messages are JSON, which contains the following f | --- | --- | --- | | `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.| +| `from` | String | Internal field. You can safely ignore it. | +| `to` | String | Internal field. You can safely ignore it. | | `chat_type` | String | The chat type: | -| `payload` | JSON | The content of the message, including message extensions and customzied message attributes. | +| `payload` | JSON | The content of the message, including message extensions and customized message attributes. | +| `payload.from` | String | The username that sends the message. | +| `payload.to` | String | The message recipient.| ```json { @@ -1705,7 +1710,7 @@ The fields of `bodies` for different message types vary: | `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. | + | `url` | String | The URL address of the vide o file. You can visit this URL to download video files. | Example: @@ -1780,26 +1785,77 @@ The fields of `bodies` for different message types vary: | Field | Type | Description | | :------------ | :----- | :----------------------------------------------- | - | `customExts` | JSON | The custom extension properties. You can set the fields in the extension properties yourself. | + | `customExts`/`v2:customExts` | JSON | The custom extension properties. You can set the fields in the extension properties yourself. `customExts`: The old parameter. It is of the Array type and can contain up to 16 elements. `v2:customExts`: The new parameter. It is of the Map type and can contain up to 16 elements. You are recommended to use this new parameter. | | `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", + "bodies": + [ + { + "v2:customExts": { + "name": "flower", + "size": "16", + "price": "100" + }, + "customExts": [ + { + "name": "flower" + }, + { + "size": "16" + }, + { "price": "100" + } + ], + "customEvent": "gift_1", + "type": "custom" + } + ] + ``` + +- Combined message + + | Parameter | Type | Description | + | :------------- | :----- | :----------------------------------------------------------- | + | `combineLevel` | Int | The number of layers of messages included in the combined message. | + | `file_length` | Int | The attachment size of the combined message, in the unit of bytes. | + | `filename` | String | The attachment name of the combined message. | + | `secret` | String | The key for accessing the attachment of the combined message. br>This field exists if you set the access restriction when calling the [upload-file](#upload) method. | + | `subType` | String | The message type, `sub_combine`, indicating the combined message. | + | `summary` | String | The summary of the combined message. | + | `title` | String | The title of the combined message. | + | `url` | String | The URL of the attachment of the combined message. You can download the attachment from the URL. | + + For example, the combined message includes a text message, an image message, and a file message. + + ```json + "bodies": + [ + { + "v2:customExts": { + "name": "flower", + "size": "16", + "price": "100" + }, + "customExts": [ + { + "name": "flower" }, - "customEvent": "gift_1", - "type": "custom" - } - ] - } + { + "size": "16" + }, + { + "price": "100" + } + ], + "customEvent": "gift_1", + "type": "custom" + } + ] ``` ## Modify a text or custom message @@ -1859,7 +1915,7 @@ If the returned HTTP status code is not `200`, the request fails. Common errors | 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. | +| `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 successfully 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. | @@ -1964,9 +2020,10 @@ For the parameters and detailed descriptions, see [Common parameters](#param). | `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. | -| `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. | +| `from` | String | No | The user who recalls the message. By default, the value is `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.
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: | +| `recallMessageExtensionInfo` | String | No | The extension information for message recall. | ### HTTP response @@ -1978,7 +2035,7 @@ If the returned HTTP status code is `200`, the request succeeds, and the respons | :--------- | :--------- | :----------------------------------------------------------- | | `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. | +| `from` | String | The user who recalls the message. | | `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. | @@ -1999,7 +2056,8 @@ curl -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json "to": "user2", "from": "user1", "chat_type": "chat", - "force": true + "force": true, + "recallMessageExtensionInfo": "{\"type\": \"chat\"}" }' ``` @@ -2072,15 +2130,17 @@ For the other parameters and detailed descriptions, see [Common parameters](#par | Parameter | Type | Required | Description | | :-------------- | :------- | :------- | :----------------------------------------------------------- | +| `Content-Type` | String | Yes | `application/json` | +| `Accept` | String | Yes | The content type. Set it to `application/json`. | | `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 | Parameter | Type | Required | Description | | :------------ | :------- | :------- | :----------------------------------------------------------- | -| `channel` | String | Yes | The ID of the conversation that you want to delete. | +| `channel` | String | Yes | The ID of the conversation that you want to delete. | | `type` | String | Yes | The type of the chat. | -| `delete_roam` | Bool | Yes | Whether to delete the chat from the server: | +| `delete_roam` | Bool | Yes | Whether to delete the roaming messages of the conversation from the server: | ### HTTP response @@ -2142,6 +2202,8 @@ POST https://{host}/{orgName}/{appName}/messages/users/import | Parameter | Type | Required | Description | | :-------------- | :------- | :------- | :----------------------------------------------------------- | +| `Content-Type` | String | Yes | `application/json` | +| `Accept` | String | Yes | The content type. Set it to `application/json`. | | `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. | @@ -2180,7 +2242,11 @@ If the request fails, refer to [Status codes](./agora_chat_status_code?platform= ```shell # Replace {YourToken} with the app token generated on your server - curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/XXXX/XXXX/messages/users/import" -d '{ + curl -X POST "https://XXXX/XXXX/XXXX/messages/users/import" \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -d '{ "target": "username2", "type": "txt", "body": { @@ -2199,7 +2265,11 @@ If the request fails, refer to [Status codes](./agora_chat_status_code?platform= ```shell # Replace {YourToken} with token generated on your server - curl -X POST -H "Authorization: Bearer {YourToken}" "https://XXXX/XXXX/XXXX/messages/users/import" -d '{ + curl -X POST "https://XXXX/XXXX/XXXX/messages/users/import" + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -d '{ "target": "username2", "type": "img", "body": { @@ -2253,6 +2323,8 @@ POST https://{host}/{orgName}/{appName}/messages/chatgroups/import | Parameter | Type | Required | Description | | :-------------- | :------- | :------- | :----------------------------------------------------------- | +| `Content-Type` | String | Yes | `application/json` | +| `Accept` | String | Yes | The content type. Set it to `application/json`. | | `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 @@ -2290,7 +2362,11 @@ If the request fails, refer to [Status codes](./agora_chat_status_code?platform= ```shell # Replace {YourAppToken} with the app token generated on your server - curl -X POST -H "Authorization: Bearer " "https://XXXX/XXXX/XXXX/messages/chatgroups/import" -d '{ + curl -X POST "https://XXXX/XXXX/XXXX/messages/chatgroups/import" + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -d '{ "target": "1123376564212", "type": "txt", "body": { diff --git a/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_reaction.md b/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_reaction.md index f42dec7ca99..2abb8fe3997 100644 --- a/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_reaction.md +++ b/en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_reaction.md @@ -70,7 +70,7 @@ For other parameters and the detailed descriptions, see [Common parameters](#par | Parameter | Type | Description | | :-------------- | :----- | :---------------------------------- | | `msg_Id` | String | The message ID to which you want to add the reaction. | -| `message` | String | The ID of the emoji, same as that on the client. The maximum length is 128 characters. | +| `message` | String | The ID of the emoji, same as that on the client. The maximum length is 128 characters. This parameter has no restriction on character set types. If special characters are used, you need to use URL encoding for the special characters when retrieving or deleting the reactions.| ### HTTP Response @@ -231,7 +231,7 @@ This method deletes a reaction. ### HTTP request ```shell -DELETE https://{host}/{org_name}/{app_name}/reaction/user/{userId} +DELETE https://{host}/{org_name}/{app_name}/reaction/user/{userId}?msgId={msgId}&message={message} ``` #### Path parameter @@ -246,8 +246,7 @@ For other parameters and the detailed descriptions, see [Common parameters](#par | Parameter | Type | Description | Required | | :-------------- | :----- | :---------------------------------- | :------- | -| `Content-Type` | String | `application/x-www-form-urlencoded` | 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 | +| `Authorization` | String | The authentication token of the 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 | #### Query parameters @@ -321,7 +320,6 @@ For other parameters and the detailed descriptions, see [Common parameters](#par | Parameter | Type | Description | Required | | :-------------- | :----- | :---------------------------------- | :------- | -| `Content-Type` | String | `application/x-www-form-urlencoded` | 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 | ### HTTP response @@ -352,8 +350,8 @@ If the returned HTTP status code is not `200`, the request fails. You can refer // Starts querying from the first page curl -g -X GET 'http://XXXX/XXXX/XXXX/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&limit=50' -H 'Authorization: Bearer {YourAppToken}' -// Starts querying from the second page -curl -g -X GET 'http://XXXX/XXXX/XXXX/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&cursor=944330529971449164&limit=50' -H 'Authorization: Authorization: Bearer {YourAppToken}' +// Starts querying from page N +curl -g -X GET 'http://XXXX/XXXX/XXXX/reaction/user/wz/detail?msgId=997627787730750008&message=emoji_40&cursor=944330529971449164&limit=50' -H 'Authorization: Bearer {YourAppToken}' ``` #### Response example