Merge pull request #279966 from huachuandeng/james/add_connectapi

add connect api to how to and remove not supporting room

Author: denrea

articles/communication-services/concepts/call-automation/call-automation.md

@@ -13,9 +13,6 @@ ms.author: askaur
 
 Azure Communication Services Call Automation provides developers the ability to build server-based, intelligent call workflows, and call recording for voice and Public Switched Telephone Network(PSTN) channels. The SDKs, available in C#, Java, JavaScript and Python, use an action-event model to help you build personalized customer interactions. Your communication applications can listen to real-time call events and perform control plane actions (like answer, transfer, play audio, start recording, etc.) to steer and control calls based on your business logic.
 
-> [!NOTE]
-> Call Automation currently doesn't support [Rooms](../rooms/room-concept.md) calls.
-
 ## Common use cases
 
 Some of the common use cases that can be built using Call Automation include:
@@ -42,6 +39,7 @@ The following list presents the set of features that are currently available in
 |                       | Place new outbound call to one or more endpoints  | ✔️    | ✔️    |     ✔️         |    ✔️   |
 |                       | Redirect* (forward) a call to one or more endpoints  | ✔️    | ✔️    |     ✔️         |    ✔️   |
 |                       | Reject an incoming call                           | ✔️    | ✔️    |     ✔️         |    ✔️   |
+|                       | Connect to an ongoing call or Room                | ✔️    | ✔️    |     ✔️         |    ✔️   |
 | Mid-call scenarios    | Add one or more endpoints to an existing call     | ✔️    | ✔️    |     ✔️         |    ✔️   |
 |                       | Cancel adding an endpoint to an existing call     | ✔️    | ✔️    |     ✔️         |    ✔️   |
 |                       | Play Audio from an audio file                     | ✔️    | ✔️    |     ✔️         |    ✔️   |
@@ -92,6 +90,9 @@ Using the IncomingCall event from Event Grid, a call can be redirected to one or
 **Create Call**
 Create Call action can be used to place outbound calls to phone numbers and to other communication users. Use cases include your application placing outbound calls to proactively inform users about an outage or notify about an order update.
 
+**Connect Call**
+Connect Call action can be used to connect to an ongoing call and take call actions on it. You can also use this action to connect and manage a Rooms call programmatically, like performing PSTN dial outs for Room using your service.  
+
 ### Mid-call actions
 
 These actions can be performed on the calls that are answered or placed using Call Automation SDKs. Each mid-call action has a corresponding success or failure web hook callback event.
@@ -159,17 +160,18 @@ The Call Automation events are sent to the web hook callback URI specified when
 
 | Event             | Description |
 | ----------------- | ------------ |
-| CallConnected      | Your application’s call leg is connected (inbound or outbound)  |
-| CallDisconnected       | Your application’s call leg is disconnected  |
-| CallTransferAccepted         | Your application’s call leg has been transferred to another endpoint  |
-| CallTransferFailed  | The transfer of your application’s call leg failed  |
-| AddParticipantSucceeded| Your application added a participant  |
-| AddParticipantFailed   | Your application was unable to add a participant  |
-| CancelAddParticipantSucceeded| Your application canceled adding a participant  |
-| CancelAddParticipantFailed   | Your application was unable to cancel adding a participant  |
-| RemoveParticipantSucceeded| Your application has successfully removed a participant from the call.  |
-| RemoveParticipantFailed   | Your application was unable to remove a participant from the call.  |
-| ParticipantsUpdated    | The status of a participant changed while your application’s call leg was connected to a call  |
+| CallConnected      | The call has successfully started (when using Answer or Create action) or your application has successfully connected to an ongoing call (when using Connect action)|
+| CallDisconnected       | Your application has been disconnected from the call |
+| ConnectFailed       | Your application failed to connect to a call (for connect call action only)|
+| CallTransferAccepted         | Transfer action has successfully completed and the transferee is connected to the target participant |
+| CallTransferFailed  | The transfer action has failed  |
+| AddParticipantSucceeded| Your application has successfully added a participant to the call  |
+| AddParticipantFailed   | Your application was unable to add a participant to the call (due to an error or the participant didn't accept the invite |
+| CancelAddParticipantSucceeded| Your application canceled an AddParticipant request successfully (i.e. the participant was not added to the call) |
+| CancelAddParticipantFailed   | Your application was unable to cancel an AddParticipant request (this could be because the request has already been processed)  |
+| RemoveParticipantSucceeded| Your application has successfully removed a participant from the call  |
+| RemoveParticipantFailed   | Your application was unable to remove a participant from the call  |
+| ParticipantsUpdated    | The status of a participant changed while your application was connected to a call  |
 | PlayCompleted | Your application successfully played the audio file provided |
 | PlayFailed | Your application failed to play audio |
 | PlayCanceled | The requested play action has been canceled |

articles/communication-services/how-tos/call-automation/actions-for-call-control.md

@@ -18,9 +18,6 @@ Call Automation uses a REST API interface to receive requests for actions and pr
 
 Call Automation supports various other actions to manage call media and recording that have separate guides.
 
-> [!NOTE]
-> Call Automation currently doesn't support [Rooms](../../concepts/rooms/room-concept.md) calls.
-
 As a prerequisite, we recommend you to read these articles to make the most of this guide:
 
 1. Call Automation [concepts guide](../../concepts/call-automation/call-automation.md#call-actions) that describes the action-event programming model and event callbacks.
@@ -169,6 +166,87 @@ The response provides you with CallConnection object that you can use to take fu
 2. `ParticipantsUpdated` event that contains the latest list of participants in the call.
 ![Sequence diagram for placing an outbound call.](media/make-call-flow.png)
 
+## Connect to a call
+Connect action enables your service to establish a connection with an ongoing call and take actions on it. This is useful to manage a Rooms call or when client applications started a 1:1 or group call that Call automation isn't part of. Connection is established using the CallLocator property and can be of types: ServerCallLocator, GroupCallLocator, and RoomCallLocator. These IDs can be found when the call is originally established or a Room is created, and also published as part of [CallStarted](./../../../event-grid/communication-services-voice-video-events.md#microsoftcommunicationcallstarted) event. 
+
+To connect to any 1:1 or group call, use the ServerCallLocator. If you started a call using GroupCallId, you can also use the GroupCallLocator. 
+### [csharp](#tab/csharp)
+
+```csharp
+Uri callbackUri = new Uri("https://<myendpoint>/Events"); //the callback endpoint where you want to receive subsequent events
+CallLocator serverCallLocator = new ServerCallLocator("<ServerCallId>");
+ConnctCallResult response = await client.ConnectAsync(serverCallLocator, callbackUri);
+```
+
+### [Java](#tab/java)
+
+```java
+String callbackUri = "https://<myendpoint>/Events"; //the callback endpoint where you want to receive subsequent events
+CallLocator serverCallLocator =  new ServerCallLocator("<ServerCallId>");
+ConnectCallResult response = client.connectCall(serverCallLocator, callbackUri).block();
+```
+
+### [JavaScript](#tab/javascript)
+
+```javascript
+const callbackUri = "https://<myendpoint>/Events"; // the callback endpoint where you want to receive subsequent events 
+const serverCallLocator = { kind: "serverCallLocator", id: "<serverCallId>" };
+const response = await client.connectCall(serverCallLocator, callbackUri);
+```
+
+### [Python](#tab/python)
+
+```python
+callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
+server_call_locator = ServerCallLocator("<server_call_id>")
+call_connection_properties = client.connect_call(call_locator=server_call_locator, callback_url=callback_uri)
+```
+
+-----
+
+To connect to a Rooms call, use RoomCallLocator which takes RoomId. 
+### [csharp](#tab/csharp)
+
+```csharp
+Uri callbackUri = new Uri("https://<myendpoint>/Events"); //the callback endpoint where you want to receive subsequent events
+CallLocator roomCallLocator = new RoomCallLocator("<RoomId>");
+ConnctCallResult response = await client.ConnectAsync(roomCallLocator, callbackUri);
+```
+
+### [Java](#tab/java)
+
+```java
+String callbackUri = "https://<myendpoint>/Events"; //the callback endpoint where you want to receive subsequent events
+CallLocator roomCallLocator =  new RoomCallLocator("<RoomId>");
+ConnectCallResult response = client.connectCall(roomCallLocator, callbackUri).block();
+```
+
+### [JavaScript](#tab/javascript)
+
+```javascript
+const roomCallLocator = { kind: "roomCallLocator", id: "<RoomId>" };
+const callbackUri = "https://<myendpoint>/Events"; // the callback endpoint where you want to receive subsequent events 
+const response = await client.connectCall(roomCallLocator, callbackUri);
+```
+
+### [Python](#tab/python)
+
+```python
+callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
+room_call_locator = RoomCallLocator("<room_id>")
+call_connection_properties = client.connect_call(call_locator=room_call_locator, callback_url=callback_uri)
+```
+
+-----
+
+A successful response provides you with CallConnection object that you can use to take further actions on this call. Two events are published to the callback endpoint you provided earlier:
+1. `CallConnected` event notifying that you successfully connect to the call.
+2. `ParticipantsUpdated` event that contains the latest list of participants in the call.
+   
+At any point after a successful connection, if your service is disconnected from this call you will be notified via a CallDisconected event. Failure to connect to the call in the first place results in ConnectFailed event.  
+
+![Sequence diagram for connecting to call.](media/connect-call-flow.png)
+
 ## Answer an incoming call
 
 Once you've subscribed to receive [incoming call notifications](../../concepts/call-automation/incoming-call-notification.md) to your resource, you will answer an incoming call. When answering a call, it's necessary to provide a callback url. Communication Services post all subsequent events about this call to that url.