Review, edite, raised Acrolinx from 82 to 100

vac0224 · web-flow · commit c77a6f354d63 · 2024-08-22T17:22:02.000-05:00
diff --git a/articles/communication-services/tutorials/includes/twilio-to-acs-chat-js-tutorial.md b/articles/communication-services/tutorials/includes/twilio-to-acs-chat-js-tutorial.md
@@ -1,6 +1,6 @@
 ---
-title: include file
-description: include file
+title: Migrating from Twilio Conversations Chat to Azure Communication Services Chat JavaScript
+description: Guide describes how to migrate JavaScript apps from Twilio Conversations Chat to Azure Communication Services Chat SDK. 
 services: azure-communication-services
 ms.date: 07/22/2024
 ms.topic: include
@@ -16,8 +16,9 @@ ms.custom: mode-other
 1.  **Azure Account:** Make sure that your Azure account is active. New users can create a free account at [Microsoft Azure](https://azure.microsoft.com/free/).
 2.  **Node.js 18:** Ensure Node.js 18 is installed on your system. Download from [Node.js](https://nodejs.org/en).
 3.  **Communication Services Resource:** Set up a [Communication Services Resource](../../quickstarts/create-communication-resource.md?tabs=windows&pivots=platform-azp) via your Azure portal and note your connection string.
-4.  **Azure CLI:** Follow the instructions to [Install Azure CLI on Windows](/cli/azure/install-azure-cli-windows?tabs=azure-cli)..
+4.  **Azure CLI:** Follow the instructions to [Install Azure CLI on Windows](/cli/azure/install-azure-cli-windows?tabs=azure-cli).
 5.  **User Access Token:** Generate a user access token to instantiate the chat client. You can create one using the Azure CLI as follows:
+
 ```console
 az communication identity token issue --scope voip --connection-string "yourConnectionString"
 ```
@@ -41,21 +42,24 @@ The `--save` option adds the library as a dependency in your **package.json** fi
 ### Remove the Twilio SDK from the project
 
 You can remove the Twilio SDK from your project by uninstalling the package.
+
 ```console
 npm uninstall twilio-conversations
 ```
 
 ## Object model
+
 The following classes and interfaces handle some of the major features of the Azure Communication Services Chat SDK for JavaScript.
 
 | Name                                   | Description                                                                                                                                                                           |
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ChatClient | This class is needed for the Chat functionality. You instantiate it with your subscription information, and use it to create, get, delete threads, and subscribe to chat events. |
-| ChatThreadClient | This class is needed for the Chat Thread functionality. You obtain an instance via the ChatClient, and use it to send/receive/update/delete messages, add/remove/get users, send typing notifications and read receipts. |
+| `ChatClient` | This class is needed for the Chat function. Instantiate it with your subscription information, and use it to create, get, delete threads, and subscribe to chat events. |
+| `ChatThreadClient` | This class is needed for the Chat Thread function. Get an instance via the `ChatClient`, and use it to send/receive/update/delete messages, add/remove/get users, send typing notifications, and read receipts. |
 
 ### Initialize the Chat Client
 
 #### Twilio
+
 ```JavaScript
 /* Initialization */
 import { Client } from '@twilio/conversations';
@@ -74,7 +78,8 @@ client.on('stateChanged', (state) => {
 });
 ```
 #### Azure Communication Services
-Similar to Twilio, the first step is to get an **access token** as well as the Communication Service **endpoint** that was generated as part of the prerequisite steps. Replace those in the code.
+
+Similar to Twilio, the first step is to get an **access token** and the Communication Service **endpoint** that was generated as part of the prerequisite steps. Replace the placeholders in the code.
 
 ```JavaScript
 import { ChatClient } from '@azure/communication-chat';
@@ -92,7 +97,8 @@ console.log('Azure Communication Chat client created!');
 ### Start a chat thread
 
 #### Twilio
-This is how you start a chat thread in Twilio Conversations. Use `FriendlyName` to give a human-readable name to this conversation.
+
+Start a chat thread in Twilio Conversations. Use `FriendlyName` to give a human-readable name to this conversation.
 
 ```JavaScript
 let conversation = await client.createConversation({
@@ -102,14 +108,15 @@ await conversation.join();
 ```
 
 #### Azure Communication Services
+
 Use the `createThread` method to create a chat thread.
 
-`createThreadRequest` is used to describe the thread request:
+Use `createThreadRequest` to describe the thread request:
 
-- Use `topic` to give a topic to this chat. Topics can be updated after the chat thread is created using the `UpdateThread` function.
+- Use `topic` to give a topic to this chat. update `topic` after you create the chat thread using the `UpdateThread` function.
 - Use `participants` to list the participants to be added to the chat thread.
 
-When resolved, `createChatThread` method returns a `CreateChatThreadResult`. This model contains a `chatThread` property where you can access the `id` of the newly created thread. You can then use the `id` to get an instance of a `ChatThreadClient`. The `ChatThreadClient` can then be used to perform operation within the thread such as sending messages or listing participants.
+When resolved, `createChatThread` method returns a `CreateChatThreadResult`. This model contains a `chatThread` property where you can access the `id` of the newly created thread. Then use the `id` to get an instance of a `ChatThreadClient`. Then use the `ChatThreadClient` to perform operation within the thread such as sending messages or listing participants.
 
 ```JavaScript
 async function createChatThread() {
@@ -136,7 +143,9 @@ async function createChatThread() {
 ### Get a chat thread client
 
 #### Twilio
-This is how you get a chat thread (conversation) in Twilio.
+
+Get a chat thread (conversation) in Twilio.
+
 ```JavaScript
 if (selectedConversation) {
       conversationContent = (
@@ -151,24 +160,30 @@ if (selectedConversation) {
       conversationContent = "";
     }
 ```
+
 #### Azure Communication Services
-The `getChatThreadClient` method returns a `chatThreadClient` for a thread that already exists. It can be used for performing operations on the created thread: add participants, send message, etc. threadId is the unique ID of the existing chat thread.
+
+The `getChatThreadClient` method returns a `chatThreadClient` for a thread that already exists. Use it to perform operations on the created thread: add participants, send message, and so on. The `threadId` is the unique ID of the existing chat thread.
 
 ```JavaScript
 let chatThreadClient = chatClient.getChatThreadClient(threadId);
 console.log(`Chat Thread client for threadId:${threadId}`);
-
 ```
-Add this code in place of the `<CREATE CHAT THREAD CLIENT>` comment in **client.js**, refresh your browser tab and check the console, you should see:
+
+Add this code in place of the `<CREATE CHAT THREAD CLIENT>` comment in **client.js**, refresh your browser tab, and check the console. You should see:
+
 ```console
 Chat Thread client for threadId: <threadId>
 ```
 
 ### Add a user as a participant to the chat thread
-Once a chat thread is created, you can then add and remove users from it. By adding users, you give them access to send messages to the chat thread and add/remove other participants.
+
+Once you create a chat thread, you can then add and remove users from it. By adding users, you give them access to send messages to the chat thread and add/remove other participants.
 
 #### Twilio
-This is how you add a participant to a chat thread.
+
+Add a participant to a chat thread.
+
 ```JavaScript
 // add chat participant to the conversation by its identity
 await conversation.add('identity');
@@ -183,9 +198,10 @@ conversation.on('participantJoined', (participant) => {
 ```
 
 #### Azure Communication Services
-Before calling the `addParticipants` method, ensure that you've acquired a new access token and identity for that user. The user will need that access token in order to initialize their chat client.
 
-`addParticipantsRequest` describes the request object wherein `participants` lists the participants to be added to the chat thread;
+Before calling the `addParticipants` method, be sure to acquire a new access token and identity for that user. The user needs that access token to initialize their chat client.
+
+`addParticipantsRequest` describes the request object wherein `participants` lists the participants to be added to the chat thread:
 - `id`, required, is the communication identifier to be added to the chat thread.
 - `displayName`, optional, is the display name for the thread participant.
 - `shareHistoryTime`, optional, is the time from which the chat history is shared with the participant. To share history since the inception of the chat thread, set this property to any date equal to, or less than the thread creation time. To share no history previous to when the participant was added, set it to the current date. To share partial history, set it to the date of your choice.
@@ -205,13 +221,16 @@ const addParticipantsRequest =
 await chatThreadClient.addParticipants(addParticipantsRequest);
 
 ```
-Replace **NEW_PARTICIPANT_USER_ID** with a [new user ID](../../identity/access-tokens.md)
+Replace **NEW_PARTICIPANT_USER_ID** with a [new user ID](../../quickstarts/identity/access-tokens.md)
 
 ### Send a message to a chat thread
-Unlike Twilio, ACS does not have separate functions for sending text messages or media.
+
+Unlike Twilio, Azure Communication Services doesn't have separate functions for sending text messages or media.
 
 #### Twilio
-This is how you send a text message in Twilio.
+
+To send a text message in Twilio.
+
 ```JavaScript
 // Send Text Message
 await conversation
@@ -222,7 +241,9 @@ await conversation
   .send();
 
 ```
-This is how you send media in Twilio.
+
+To send media in Twilio.
+
 ```JavaScript
  const file =
   await fetch("https://v.fastcdn.co/u/ed1a9b17/52533501-0-logo.svg");
@@ -242,20 +263,22 @@ await conversation
 ```
 
 #### Azure Communication Services
+
 Use `sendMessage` method to send a message to a thread identified by threadId.
 
 `sendMessageRequest` is used to describe the message request:
 
-- Use `content` to provide the chat message content;
+- Use `content` to provide the chat message content.
 
-`sendMessageOptions` is used to describe the operation optional params:
+Use `sendMessageOptions` to describe the operation optional params:
 
-- Use `senderDisplayName` to specify the display name of the sender;
-- Use `type` to specify the message type, such as 'text' or 'html';
-This is how you accomplish the "Media" property in Twilio.
-- Use `metadata` optionally to include any other data you want to send along with the message. This field provides a mechanism for developers to extend chat message functionality and add custom information for your use case. For example, when sharing a file link in the message, you might want to add 'hasAttachment: true' in metadata so that recipient's application can parse that and display accordingly. Please refer to the [following tutorial](../file-sharing-tutorial-acs-chat.md).
+- Use `senderDisplayName` to specify the display name of the sender.
+- Use `type` to specify the message type, such as `text` or `html`.
 
-`SendChatMessageResult` is the response returned from sending a message, it contains an ID, which is the unique ID of the message.
+To recreate the "Media" property in Twilio.
+- Use `metadata` optionally to include any other data you want to send along with the message. This field enables developers to extend the chat message function and add custom information for your use case. For example, when sharing a file link in the message, you might want to add `hasAttachment: true` in metadata so that recipient's application can parse that and display accordingly. For more information, see [File sharing](../file-sharing-tutorial-acs-chat.md).
+
+`SendChatMessageResult` is the response returned from sending a message. It contains an ID, which is the unique ID of the message.
 
 ```JavaScript
 const sendMessageRequest =
@@ -277,10 +300,13 @@ console.log(`Message sent!, message id:${messageId}`);
 ```
 
 ### Receive chat messages from a chat thread
-Unlike Twilio, ACS does not have separate functions to receive text messages or media. Azure Communication Services uses Azure Event Grid to handle events. To learn more, please refer to [following tutorial](MicrosoftDocs/azure-docs-pr/articles/event-grid/event-schema-communication-services.md)
+
+Unlike Twilio, Azure Communication Services doesn't have separate functions to receive text messages or media. Azure Communication Services uses Azure Event Grid to handle events. For more information, see [Event Handling](/azure/event-grid/event-schema-communication-services.md).
 
 #### Twilio
-This is how you receive a text message in Twilio.
+
+To receive a text message in Twilio.
+
 ```JavaScript
 // Receive text message
  let paginator =
@@ -290,7 +316,8 @@ This is how you receive a text message in Twilio.
 
 const messages = paginator.items;
 ```
-This is how you receive media in Twilio.
+
+To receive media in Twilio.
 
 ```JavaScript
 // Receive media
@@ -302,7 +329,8 @@ const mediaUrl = await media[0].getContentTemporaryUrl();
 ```
 
 #### Azure Communication Services
-With real-time signaling, you can subscribe to listen for new incoming messages and update the current messages in memory accordingly. Azure Communication Services supports a [list of events that you can subscribe to](../../../concepts/chat/concepts.md#real-time-notifications).
+
+With real-time signaling, you can subscribe to listen for new incoming messages and update the current messages in memory accordingly. Azure Communication Services supports a [list of events that you can subscribe to](../../concepts/chat/concepts.md#real-time-notifications).
 
 ```JavaScript
 // open notifications channel
@@ -325,15 +353,16 @@ for await (const message of messages) {
 }
 
 ```
-`listMessages` returns different types of messages that can be identified by `chatMessage.type`. 
 
-For more details, see [Message Types](../../../concepts/chat/concepts.md#message-types).
+`listMessages` returns different types of messages that you can identify by `chatMessage.type`. 
 
+For more information, see [Message Types](../../concepts/chat/concepts.md#message-types).
 
 #### Subscribe to connection status of real time notifications
-Similar to Twilio, Azure Communication Services allows you to subscribe to event notifications.
 
-Subscription to events `realTimeNotificationConnected` and `realTimeNotificationDisconnected` allows you to know when the connection to the call server is active.
+Similar to Twilio, Azure Communication Services enables you to subscribe to event notifications.
+
+Subscribing to events `realTimeNotificationConnected` and `realTimeNotificationDisconnected` lets you know when the connection to the call server is active.
 
 ```JavaScript
 // subscribe to realTimeNotificationConnected event
