|
| 1 | +--- |
| 2 | +title: Call Automation overview |
| 3 | +titleSuffix: An Azure Communication Services concept document |
| 4 | +description: Learn about Azure Communication Services Call Automation. |
| 5 | +author: ashwinder |
| 6 | + |
| 7 | +ms.service: azure-communication-services |
| 8 | +ms.topic: include |
| 9 | +ms.date: 09/06/2022 |
| 10 | +ms.author: askaur |
| 11 | +ms.custom: private_preview |
| 12 | +--- |
| 13 | +# Call Automation Overview |
| 14 | + |
| 15 | +> [!IMPORTANT] |
| 16 | +> Functionality described on this document is currently in private preview. Private preview includes access to SDKs and documentation for testing purposes that are not yet available publicly. |
| 17 | +> Apply to become an early adopter by filling out the form for [preview access to Azure Communication Services](https://aka.ms/ACS-EarlyAdopter). |
| 18 | +
|
| 19 | +Azure Communication Services Call Automation provides developers the ability to build server-based, intelligent call workflows for voice and PSTN channels. The SDKs, available for .NET and Java, uses 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, etc.) to steer and control calls based on your business logic. |
| 20 | + |
| 21 | +## Common Use Cases |
| 22 | + |
| 23 | +Some of the common use cases that can be build using Call Automation include: |
| 24 | + |
| 25 | +- Program VoIP or PSTN calls for transactional workflows such as click-to-call and appointment reminders to improve customer service. |
| 26 | +- Build interactive interaction workflows to self-serve customers for use cases like order bookings and updates, using Play (Audio URL) and Recognize (DTMF) actions. |
| 27 | +- Integrate your communication applications with Contact Centers and your private telephony networks using Direct Routing. |
| 28 | +- Protect your customer's identity by building number masking services to connect buyers to sellers or users to partner vendors on your platform. |
| 29 | +- Increase engagement by building automated customer outreach programs for marketing and customer service. |
| 30 | + |
| 31 | +ACS Call Automation can be used to build calling workflows for customer service scenarios, as depicted in the high-level architecture below. You can answer inbound calls or make outbound calls. Execute actions like playing a welcome message, connecting the customer to a live agent on an ACS Calling SDK client app to answer the incoming call request. With support for ACS PSTN or Direct Routing, you can then connect this workflow back to your contact center. |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +## Capabilities |
| 36 | + |
| 37 | +The following list presents the set of features that are currently available in the Azure Communication Services Call Automation SDKs. |
| 38 | + |
| 39 | +| Feature Area | Capability | .NET | Java | |
| 40 | +| ----------------------| ----------------------------------------------- | ------ | ----- | |
| 41 | +| Pre-call scenarios | Answer a one-to-one call | ✔️ | ✔️ | |
| 42 | +| | Answer a group call | ✔️ | ✔️ | |
| 43 | +| | Place new outbound call to one or more endpoints | ✔️ | ✔️ | |
| 44 | +| | Redirect* (forward) a call to one or more endpoints | ✔️ | ✔️ | |
| 45 | +| | Reject an incoming call | ✔️ | ✔️ | |
| 46 | +| Mid-call scenarios | Add one or more endpoints to an existing call | ✔️ | ✔️ | |
| 47 | +| | Play Audio from an audio file | ✔️ | ✔️ | |
| 48 | +| | Remove one or more endpoints from an existing call| ✔️ | ✔️ | |
| 49 | +| | Blind Transfer** a call to another endpoint | ✔️ | ✔️ | |
| 50 | +| | Hang up a call (remove the call leg) | ✔️ | ✔️ | |
| 51 | +| | Terminate a call (remove all participants and end call)| ✔️ | ✔️ | |
| 52 | +| Query scenarios | Get the call state | ✔️ | ✔️ | |
| 53 | +| | Get a participant in a call | ✔️ | ✔️ | |
| 54 | +| | List all participants in a call | ✔️ | ✔️ | |
| 55 | + |
| 56 | +*Redirecting a call to a phone number is currently not supported. |
| 57 | + |
| 58 | +**Transfer of VoIP call to a phone number is currently not supported. |
| 59 | + |
| 60 | +## Architecture |
| 61 | + |
| 62 | +Call Automation uses a REST API interface to receive requests and provide responses to all actions performed within the service. Due to the asynchronous nature of calling, most actions will have corresponding events that are triggered when the action completes successfully or fails. |
| 63 | + |
| 64 | +Event Grid – Azure Communication Services uses Event Grid to deliver the IncomingCall event. This event can be triggered: |
| 65 | +- by an inbound PSTN call to a number you've acquired in the portal, |
| 66 | +- by connecting your telephony infrastructure using an SBC, |
| 67 | +- for one-on-one calls between Communication Service users, |
| 68 | +- when a Communication Services user is added to an existing call (group call), |
| 69 | +- an existing 1:1 call is transferred to a Communication Service user. |
| 70 | + |
| 71 | +Web hooks – Calling Automation SDKs use standard web hook HTTP/S callbacks for call state change events and responses to mid-call actions. |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | +## Call Actions |
| 77 | + |
| 78 | +### Pre-call actions |
| 79 | + |
| 80 | +These actions are performed before the destination endpoint listed in the IncomingCall event notification is connected. Web hook callback events only communicate the “answer” pre-call action, not for reject or redirect actions. |
| 81 | + |
| 82 | +**Answer** – Using the IncomingCall event from Event Grid and Call Automation SDK, a call can be answered by your application. This action allows for IVR scenarios where an inbound PSTN call can be answered programmatically by your application. Other scenarios include answering a call on behalf of a user. |
| 83 | + |
| 84 | +**Reject** – To reject a call means your application can receive the IncomingCall event and prevent the call from being connected to the destination endpoint. |
| 85 | + |
| 86 | +**Redirect** – Using the IncomingCall event from Event Grid, a call can be redirected to one or more endpoints creating a single or simultaneous ringing (sim-ring) scenario. This means the call isn't answered by your application, it's simply ‘redirected’ to another destination endpoint to be answered. |
| 87 | + |
| 88 | +**Make Call** - Make 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. |
| 89 | + |
| 90 | +### Mid-call actions |
| 91 | + |
| 92 | +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. |
| 93 | + |
| 94 | +**Add/Remove participant(s)** – One or more participants can be added in a single request with each participant being a variation of supported destination endpoints. A web hook callback is sent for every participant successfully added to the call. |
| 95 | + |
| 96 | +**Play** - When your application answers a call or places an outbound call, you can play an audio prompt for the caller. This audio can be looped if needed in scenarios like playing hold music. To learn more, view our [quickstart](../../quickstarts/voice-video-calling/play-action.md) |
| 97 | + |
| 98 | +**Transfer** – When your application answers a call or places an outbound call to an endpoint, that endpoint can be transferred to another destination endpoint. Transferring a 1:1 call will remove your application's ability to control the call using the Call Automation SDKs. |
| 99 | + |
| 100 | +**Hang-up** – When your application has answered a one-to-one call, the hang-up action will remove the call leg and terminate the call with the other endpoint. If there are more than two participants in the call (group call), performing a ‘hang-up’ action will remove your application’s endpoint from the group call. |
| 101 | + |
| 102 | +**Terminate** – Whether your application has answered a one-to-one or group call, or placed an outbound call with one or more participants, this action will remove all participants and end the call. This operation is triggered by setting `forEveryOne` property to true in Hang-Up call action. |
| 103 | + |
| 104 | +## Events |
| 105 | + |
| 106 | +The following table outlines the current events emitted by Azure Communication Services. The two tables below show events emitted by Event Grid and from the Call Automation as webhook events. |
| 107 | + |
| 108 | +### Event Grid events |
| 109 | + |
| 110 | +Most of the events sent by Event Grid are platform agnostic meaning they're emitted regardless of the SDK (Calling or Call Automation). While you can create a subscription for any event, we recommend you use the IncomingCall event for all Call Automation use-cases where you want to control the call programmatically. Use the other events for reporting/telemetry purposes. |
| 111 | + |
| 112 | +| Event | Description | |
| 113 | +| ----------------- | ------------ | |
| 114 | +| IncomingCall | Notification of a call to a communication user or phone number | |
| 115 | +| CallStarted | A call is established (inbound or outbound) | |
| 116 | +| CallEnded | A call is terminated and all participants are removed | |
| 117 | +| ParticipantAdded | A participant has been added to a call | |
| 118 | +| ParticipantRemoved| A participant has been removed from a call | |
| 119 | + |
| 120 | +### Call Automation webhook events |
| 121 | + |
| 122 | +The Call Automation events are sent to the web hook callback URI specified when you answer or place a new outbound call. |
| 123 | +| Event | Description | |
| 124 | +| ----------------- | ------------ | |
| 125 | +| CallConnected | Your application’s call leg is connected (inbound or outbound) | |
| 126 | +| CallDisconnected | Your application’s call leg is disconnected | |
| 127 | +| CallTransferAccepted | Your application’s call leg has been transferred to another endpoint | |
| 128 | +| CallTransferFailed | The transfer of your application’s call leg failed | |
| 129 | +| AddParticipantSucceeded| Your application added a participant | |
| 130 | +|AddParticipantFailed | Your application was unable to add a participant | |
| 131 | +| RemoveParticipantSucceeded|Your application removed a participant | |
| 132 | +| RemoveParticipantFailed |Your application was unable to remove a participant | |
| 133 | +| ParticipantUpdated | The status of a participant changed while your application’s call leg was connected to a call | |
| 134 | +| PlayCompleted| Your application successfully played the audio file provided | |
| 135 | +| PlayFailed| Your application failed to play audio | |
| 136 | + |
| 137 | +## Known Issues |
| 138 | + |
| 139 | +1. Using the incorrect IdentifierType for endpoints for `Transfer` requests (like using CommunicationUserIdentifier to specify a phone number) returns a 500 error instead of a 400 error code. Solution: Use the correct type, CommunicationUserIdentifier for Communication Users and PhoneNumberIdentifier for phone numbers. |
| 140 | +2. Taking a pre-call action like Answer/Reject on the original call after redirected it gives a 200 success instead of failing on 'call not found'. |
| 141 | + |
| 142 | +## Next Steps |
| 143 | + |
| 144 | +> [!div class="nextstepaction"] |
| 145 | +> [Get started with Call Automation](./../../quickstarts/voice-video-calling/Callflows-for-customer-interactions.md) |
0 commit comments