Merge pull request #3311 from haoxiuwen/agora-chat

Modify Agora Chat EN Docs

en-US/markdown/agora-chat/Develop/Chat Groups/agora_chat_group_overview.md

@@ -25,7 +25,8 @@ The specific feature differences are listed in the following table:
 | Use cases  | Group chat scenarios in Signal and Skype, where members have a preexisting relationship with each other. | Stream chat scenarios in Twitch, where viewers have no relationship with each other. Once a member quits the stream channel, they leave the chat room.  |
 | Maximum number of members | 5,000 | 20,000+  |
 | Message push support | Members receive push messages when they go offline. | Members do not receive push messages when they go offline. |
-| Message storage support | Supports message storage when a member is offline. Once online, this member receives all the stored messages. A maximum number of 200 messages can be stored for each group chat thread.   | This feature can be enabled and disabled. If you enable this feature, the SDK supports message storage when a member is offline. Once online, this member receives all the stored messages. By default, 10 messages can be stored for each chat room thread, and you can set this number to a maximum value of 200. |
+| Offline message storage   | This feature is supported. The server stores messages sent to offline group members and sends to them once they gets online. A maximum number of 200 messages can be stored for each group conversation. | This feature is disabled for chat rooms by default. To enable it, contact [email protected]. After this feature is enabled, when a user joins a chat room, the server sends the latest 10 historical messages to the client side via the message receiving callback. The number of historical messages sent to the new chat room member can be increased up to 200. |
+| Historical message storage  | This feature is supported. You can get historical messages of a conversation from the server.   | This feature is not supported for chat rooms. |
 | Message reliablity | All members receive all the messages in the chat group. | Members might not see all messages. The SDK discards messages if the chat group message threshold is exceeded. The default threshold is 100 messages per second. You can adjust this threshold according to your needs.  |
 
 

en-US/markdown/agora-chat/Develop/Messages/Manage Local Messages/agora_chat_manage_message_flutter.md

@@ -44,20 +44,16 @@ try {
 You can retrieve the messages in the specified conversation from the local database by specifying the conversation ID and chat type:
 
 ```dart
-// The conversation ID.
-String convId = "convId";
-// Whether to create a conversation if the specified one does not exist. If you set it as true, the SDK returns a conversation object.
-bool createIfNeed = true;
-// The conversation type.
-ChatConversationType conversationType = ChatConversationType.Chat;
-// Call getConversation to get the specified conversation.
-ChatConversation? conversation =
-    await ChatClient.getInstance.chatManager.getConversation(
-  convId,
-  conversationType,
-  true,
-);
-List<ChatMessage>? list = await conversation?.loadMessages();   
+// Retrieves the conversation ID
+ChatConversation? conversation = await ChatClient.getInstance.chatManager
+    .getConversation(conversationId, type: ChatConversationType.Chat);
+
+// Only one message is loaded during SDK initialization. Call loadMessages to retrieve more messages.
+List<ChatMessage> messages = await conversation!.loadMessages(
+  startMsgId: startMsgId,
+  loadCount: count,
+  direction: ChatSearchDirection.Up,
+);  
 ```
 
 ### Retrieve the count of unread messages in the specified conversation

en-US/markdown/agora-chat/Develop/agora_chat_set_up_webhooks.md

@@ -60,29 +60,31 @@ To receive the HTTP callbacks, you need to configure rules for the pre- or post-
 
 1. Log in to Agora Console and find your project on the Project Management page, then click the edit button.
 2. Find **Agora Chat** on the project editing page, and click **Configure**.
-3. Click **Add Target Url** in the **Real-time Callback** section on the configuration page.
+3. Choose **Features** > **Callback** and click **Add Callback Address** on the **Callback** page.
 
-	  ![](https://web-cdn.agora.io/docs-files/1645523175808)
+	  ![](callback_addr_list.png)
 		
-4. To add a rule for pre-delivery callbacks, fill the following fields under the **pre send** tab and then click **Save**.
+4. To add a rule for pre-delivery callbacks, fill the following fields under the **Pre Send** tab and then click **Save**.
 
      - Rule Name: Enter a name for the rule. Under one project, each rule must have a unique name.
      - Chat Type: Select the types of chat this rule applies to.
      - Message Type: Select the types of messages this rule applies to.
-     - Timeout: (Optional) Specify the time (in ms) that the Agora Chat server should wait for the HTTP responses. The default value is 200 ms. If the reponse times out, the Agora Chat server continues with the fallback action.
-     - Fallback Action: (Optional) Select the action of the Agora Chat server when the HTTP response times out or returns errors. The default option is pass.
-     - Target Url: Enter the URL of your app server for receiving the pre-delivery callbacks. Supports both HTTP and HTTPS URLs.
-     - Rejection Behaviour: (Optional) Set whether to notify the message sender when their message is rejected. The default option is to not notify the message sender.
+     - Timeout: (Optional) Specify the time (in ms) that the Agora Chat server should wait for the HTTP responses. The default value is 200 ms. If the response times out, the Agora Chat server continues with the fallback action.
+     - Fallback Action: (Optional) Select the action of the Agora Chat server when the HTTP response times out or an error is returned. The default value is **Passed**.
+     - Report Error: (Optional) Set whether to notify the message sender when their message is rejected. The default value is **No**, indicating that the sender is not notified of the message delivery failure.
+     - Status: Set whether to enable this rule. The default value is **Enabled**.
+     - Callback Address: Enter the URL of your app server for receiving the pre-delivery callbacks. Both HTTP and HTTPS URLs are allowed.
+
 
-5. To add a rule for post-delivery callbacks, fill the following fields under the **post send** tab and then click **Save**.
+5. To add a rule for post-delivery callbacks, fill the following fields under the **Post Send** tab and then click **Save**.
 
      - Rule Name: Enter a name for the rule. Under one project, each rule must have a unique name.
      - Callback Service: Select the types of chat or events this rule applies to.
-     - Message Type: Select the types of messages this rule applies to.
      - Message Status: Select whether this rule applies to chat or offline messages, or both.
      - To synchronize the chat history on your own server, select chat messages. All messages sent by the users are chat messages, regardless of the online status of the message receiver.
      - To push message notifications, select offline messages. Messages sent to an offline user are counted as offline messages.
-     - Target Url: Enter the URL of your app server for receiving the post-delivery callbacks. Supports both HTTP and HTTPS URLs.
+     - Status: Set whether to enable this rule. The default value is **Disabled**.
+     - Callback Address: Enter the URL of your app server for receiving the post-delivery callbacks. Both HTTP and HTTPS URLs are allowed.
 
 The rules take effect immediately.
 
@@ -99,10 +101,10 @@ To enhance the security of the callbacks, Agora Chat includes a signature in the
 To verify the signature in a callback, do the following:
 
 1. Retrive the following information:
-    - The callback ID, which is the callId paramater in the request body of the callback. 
+    - The callback ID, which is the callId parameter in the request body of the callback. 
     - The secret assigned to the callback rule. You can find this value on the Agora Chat configuration page in Agora Console. 
 
-		![](https://web-cdn.agora.io/docs-files/1645523345319)
+		![](callback_secret.png)
 		
 	- The callback timestamp, which is the timestamp parameter in the request body of the callback.
 

en-US/markdown/agora-chat/RESTful API Reference/Chat Group Management/agora_chat_restful_group_create.md

@@ -71,9 +71,11 @@ For the descriptions of other path parameters, see [Common Parameters](#param).
 | `groupname` | String | The group name. It cannot exceed 128 characters. | Yes |
 | `desc` | String | The group description. It cannot exceed 512 characters. | Yes |
 | `public` | Boolean | Whether the group is a public group. Public groups can be searched and chat users can apply to join a public group. Private groups cannot be searched, and chat users can join a private group only if the group owner or admin invites the user to join the group.<ul><li>`true`: Yes</li><li>`false`: No</li></ul> | Yes |
+| `scale`           | String | The group scale. The parameter value depends on the setting of `maxusers`. <ul><li>(Default) `normal`: Normal group that has a maximum of 3000 members. </li><li>`large`: Large group that has more than 3000 members. You must set this parameter when you create a large group. Large groups do not support offline push. | No |
 | `maxusers` | String | The maximum number of chat group members (including the group owner). The default value is 200. The upper limit varies with your price plans. For details, see [Pricing Plan Details](./agora_chat_plan#group). | No |
 | `allowinvites` | Boolean | Whether a regular group member is allowed to invite other users to join the chat group.<ul><li>`true`: Yes.</li><li>`false`: No. Only the group owner or admin can invite other users to join the chat group. </li></ul> | No |
 | `membersonly` | Boolean | Whether the user requesting to join the public group requires approval from the group owner or admin:<ul><li>`true`: Yes.</li><li>`false`: (Default) No.</li></ul> | No |
+| `invite_need_confirm` | Boolean | Whether the invitee needs to confirm the received group invitation before joining the group:<ul><li>`true`: Yes. </li><li>`false`: No. The invitee automatically joins the chat group after receiving the group invitation.</li></ul> | No|
 | `owner` | String | The chat group owner. | Yes |
 | `members` | Array | Regular chat group members. This chat group member array does not contain the group owner. If you want to set this field, you can enter 1 to 100 elements in this array. | No |
 | `custom` | String | The extension information of the chat group. The extension information cannot exceed 1024 characters. | No |

en-US/markdown/agora-chat/RESTful API Reference/agora_chat_restful_presence.md

@@ -30,7 +30,7 @@ In order to improve the security of the project, Agora uses a token (dynamic key
 
 ## Set the presence status of a user
 
-Sets the presence status of a user.
+Sets the user's presence status on a specific device.
 
 For each App Key, the call frequency limit of this method is 50 per second.
 
@@ -44,8 +44,9 @@ POST https://{host}/{org_name}/{app_name}/users/{uid}/presence/{resource}/{statu
 
 | Parameter | Type | Description | Required |
 |:---------------| :------ | :------- |:------------------|
-| `resource` | String | The unique identifier assigned to each device resource in the format `{Device Type}_{Resource ID}`, where the device type can be `android`, `ios`, or `web`, followed by a resource ID assigned by the SDK.  | Yes |
-| `status` | String | The presence status defined by the user:<li>`0`: Offline.<li>`1`: Online<li>Other strings: Custom status. | Yes |
+| `uid` | String | The user ID of user whose presence status is to be set. | Required |
+| `resource` | String | The ID of the user's device for which the presence status is set. This device ID is the unique identifier assigned to each device resource in the format `{Device Platform}_{Resource ID}`, where the device platform can be `android`, `ios`, or `webim`, followed by an underscore plus a resource ID assigned by the SDK. For example, `android_34f0bbf7-8eab-46db-b572-b56b02405690`.| Yes |
+| `status` | String | The presence status defined by the user:<li>`0`: Offline.<li>`1`: Online<li>Other numeric strings: Custom status. | Yes |
 
 For the descriptions of the other path parameters, see [Common Parameters](#param).
 
@@ -79,8 +80,8 @@ If the returned HTTP status code is not `200`, the request fails. You can refer
 #### Request example
 
 ```json
-curl -X POST 'a1-test.agora.com:8089/5101220107132865/test/users/c1/presence/android_123423453246/0' \
--H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
+curl -X POST 'http://XXXX/XXXX/XXXX/users/c1/presence/android_123423453246/0' \
+-H 'Authorization: Bearer <YourAppToken>' \
 -H 'Content-Type: application/json' \
 -d '{"ext":"123"}'
 ```
@@ -147,8 +148,8 @@ If the returned HTTP status code is not `200`, the request fails. You can refer
 #### Request example
 
 ```json
-curl -X POST 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence/1000' \
--H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
+curl -X POST 'http://XXXX/XXXX/XXXX/users/wzy/presence/1000' \
+-H 'Authorization: Bearer <YourAppToken>' \
 -H 'Content-Type: application/json' \
 -d '{"usernames":["c2","c3"]}'
 ```
@@ -210,8 +211,8 @@ If the returned HTTP status code is not `200`, the request fails. You can refer
 #### Request example
 
 ```json
-curl -X POST 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence' \
--H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
+curl -X POST 'http://XXXX/XXXX/XXXX/users/wzy/presence' \
+-H 'Authorization: Bearer <YourAppToken>' \
 -H 'Content-Type: application/json' \
 -d '{"usernames":["c2","c3"]}'
 ```
@@ -282,8 +283,8 @@ If the returned HTTP status code is not `200`, the request fails. You can refer
 #### Request example
 
 ```json
-curl -X DELETE 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence' \
--H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
+curl -X DELETE 'http://XXXX/XXXX/XXXX/users/wzy/presence' \
+-H 'Authorization: Bearer <YourAppToken>' \
 -H 'Content-Type: application/json' \
 -d '["c1"]'
 ```
@@ -345,8 +346,8 @@ If the returned HTTP status code is not `200`, the request fails. You can refer
 #### Request example
 
 ```json
-curl -X GET 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence/sublist?pageNum=1&pageSize=100' \
--H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
+curl -X GET 'http://XXXX/XXXX/XXXX/users/wzy/presence/sublist?pageNum=1&pageSize=100' \
+-H 'Authorization: Bearer <YourAppToken>' \
 -H 'Content-Type: application/json' 
 ```