You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/communication-services/concepts/call-automation/call-automation.md
+47-61Lines changed: 47 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,22 +15,22 @@ Azure Communication Services Call Automation provides developers the ability to
15
15
16
16
## Common use cases
17
17
18
-
Some of the common use cases that can be built using Call Automation include:
18
+
Some of the common use cases that you can build using Call Automation:
19
19
20
20
- Program VoIP or PSTN calls for transactional workflows such as click-to-call and appointment reminders to improve customer service.
21
-
- Build interactive interaction workflows to self-serve customers for use cases like order bookings and updates, using Play (Audio URL, Text-to-Speech and SSML) and Recognize (DTMF and Voice) actions.
21
+
- Build interactive interaction workflows to self-serve customers for use cases like order bookings and updates, using Play (Audio URL, Text-to-Speech, and SSML) and Recognize (DTMF and Voice) actions.
22
22
- Integrate your communication applications with Contact Centers and your private telephony networks using Direct Routing.
23
23
- Protect your customer's identity by building number masking services to connect buyers to sellers or users to partner vendors on your platform.
24
24
- Increase engagement by building automated customer outreach programs for marketing and customer service.
25
25
- Analyze in a post-call process your unmixed audio recordings for quality assurance purposes.
26
26
27
-
Azure Communication Services Call Automation can be used to build calling workflows for customer service scenarios, as depicted in the high-level architecture. 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 Azure Communication Services Calling SDK client app to answer the incoming call request. With support for Azure Communication Services PSTN or Direct Routing, you can then connect this workflow back to your contact center.
27
+
Use Azure Communication Services Call Automation to build calling workflows for customer service scenarios, as depicted in the high-level architecture. You can answer inbound calls or make outbound calls. Execute actions like play a welcome message or connect the customer to a live agent on an Azure Communication Services Calling SDK client app to answer the incoming call request. With support for Azure Communication Services PSTN or Direct Routing, you can then connect this workflow back to your contact center.
28
28
29
29
30
30
31
31
## Capabilities
32
32
33
-
The following list presents the set of features that are currently available in the Azure Communication Services Call Automation SDKs.
33
+
The following features are currently available in the Azure Communication Services Call Automation SDKs.
*Redirect of a VoIP call to a phone number is not supported.
65
+
\* Transfer or redirect of a VoIP call to a phone number is currently not supported.
66
66
67
67
## Architecture
68
68
@@ -76,16 +76,13 @@ Azure Communication Services uses Event Grid to deliver the [IncomingCall event]
76
76
77
77
### Pre-call actions
78
78
79
-
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.
79
+
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.
80
80
81
-
**Answer**
82
-
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 your application can programmatically answer inbound PSTN calls. Other scenarios include answering a call on behalf of a user.
81
+
**Answer** – Using the IncomingCall event from Event Grid and Call Automation SDK, your application can answer a call. Use this action in IVR scenarios where your application can programmatically answer inbound PSTN calls. Other scenarios include answering a call on behalf of a user.
83
82
84
-
**Reject**
85
-
To reject a call means your application can receive the IncomingCall event and prevent the call from being connected to the destination endpoint.
83
+
**Reject** – To reject a call means your application can receive the `IncomingCall` event and prevent the call from being connected to the destination endpoint.
86
84
87
-
**Redirect**
88
-
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. Redirect action doesn't answer the call, the call is simply redirected or forwarded to another destination endpoint to be answered.
85
+
**Redirect** – Using the `IncomingCall` event from Event Grid, you can redirect a call to one or more endpoints creating a single or simultaneous ringing (sim-ring) scenario. Redirect action doesn't answer the call. The call is redirected or forwarded to another destination endpoint to be answered.
89
86
90
87
**Create Call**
91
88
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.
@@ -95,64 +92,52 @@ Connect Call action can be used to connect to an ongoing call and take call acti
95
92
96
93
### Mid-call actions
97
94
98
-
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.
95
+
Your application can perform these actions on calls that are answered or placed using Call Automation SDKs. Each mid-call action has a corresponding success or failure web hook callback event.
99
96
100
-
**Add/Remove participant(s)**
101
-
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.
97
+
**Add/Remove participant(s)** – You can add one or more participants 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.
102
98
103
-
**Play**
104
-
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 [concepts](./play-action.md) and how-to guide for [Customizing voice prompts to users with Play action](../../how-tos/call-automation/play-action.md).
99
+
**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, see [Playing audio in call](./play-action.md) and [Customizing voice prompts to users with Play action](../../how-tos/call-automation/play-action.md).
105
100
106
-
**Recognize input**
107
-
After your application has played an audio prompt, you can request user input to drive business logic and navigation in your application. To learn more, view our [concepts](./recognize-action.md) and how-to guide for [Gathering user input](../../how-tos/call-automation/recognize-action.md).
101
+
**Recognize input** – After your application plays an audio prompt, you can request user input to drive business logic and navigation in your application. To learn more, see [Gathering user input](./recognize-action.md) and the how-to guide [Gather user input with Recognize action](../../how-tos/call-automation/recognize-action.md).
108
102
109
-
**Continuous DTMF recognition**
110
-
When your application needs to be able to receive DTMF tones at any point in the call without the application needing to trigger a specific recognize action. This can be useful in scenarios where an agent is on a call and needs the user to enter in some kind of ID or tracking number. To learn more about how to use this view our [guide](../../how-tos/call-automation/control-mid-call-media-actions.md).
103
+
**Continuous DTMF recognition** – When your application needs to be able to receive DTMF tones at any point in the call without the application needing to trigger a specific recognize action. This ability can be useful in scenarios where an agent is on a call and needs the user to enter in some kind of ID or tracking number. To learn more, see [How to control mid-call media actions](../../how-tos/call-automation/control-mid-call-media-actions.md).
111
104
112
-
**Send DTMF**
113
-
When your application needs to send DTMF tones to an external participant, this could be for purposes like dialing out to an external agent and providing the extension number, or something like navigating an external IVR menu.
105
+
**Send DTMF** – When your application needs to send DTMF tones to an external participant. Use this action for dialing out to an external agent and providing the extension number, or navigating an external IVR menu.
114
106
115
-
**Mute**
116
-
Your application can mute certain users based on your business logic. The user would then need to unmute themselves manually if they want to speak.
107
+
**Mute** – Your application can mute certain users based on your business logic. The user would then need to unmute themselves manually if they want to speak.
117
108
118
-
**Transfer**
119
-
When your application answers a call or places an outbound call to an endpoint, that call can be transferred to another destination endpoint. Transferring a 1:1 call removes your application's ability to control the call using the Call Automation SDKs.
109
+
**Transfer** – When your application answers a call or places an outbound call to an endpoint, that call can be transferred to another destination endpoint. Transferring a 1:1 call removes your application's ability to control the call using the Call Automation SDKs.
120
110
121
-
**Record**
122
-
You decide when to start/pause/resume/stop recording based on your application business logic, or you can grant control to the end user to trigger those actions. To learn more, view our [concepts](./../voice-video-calling/call-recording.md) and [quickstart](../../quickstarts/voice-video-calling/get-started-call-recording.md).
111
+
**Record** – You decide when to start/pause/resume/stop recording based on your application business logic, or you can grant control to the end user to trigger those actions. To learn more, view our [concepts](./../voice-video-calling/call-recording.md) and [quickstart](../../quickstarts/voice-video-calling/get-started-call-recording.md).
123
112
124
-
**Hang-up**
125
-
When your application has answered a one-to-one call, the hang-up action removes the call leg and terminates the call with the other endpoint. If there are more than two participants in the call (group call), performing a ‘hang-up’ action removes your application’s endpoint from the group call.
113
+
**Hang-up** – When your application answers a one-to-one call, the hang-up action removes the call leg and terminates the call with the other endpoint. If there are more than two participants in the call (group call), performing a ‘hang-up’ action removes your application’s endpoint from the group call.
126
114
127
-
**Terminate**
128
-
Whether your application has answered a one-to-one or group call, or placed an outbound call with one or more participants, this action removes all participants and ends the call. This operation is triggered by setting `forEveryOne` property to true in Hang-Up call action.
115
+
**Terminate** – Whether your application answers a one-to-one or group call, or places an outbound call with one or more participants, this action removes all participants and ends the call. This operation is triggered by setting the `forEveryOne` property to `true` in Hang-Up call action.
129
116
130
-
**Cancel media operations**
131
-
Based on business logic your application may need to cancel ongoing and queued media operations. Depending on the media operation canceled and the ones in queue, you'll receive a webhook event indicating that the action has been canceled.
117
+
**Cancel media operations** – Based on business logic your application may need to cancel ongoing and queued media operations. Depending on the media operation canceled and the ones in queue, your application might receive a webhook event indicating that the action was canceled.
132
118
133
119
### Query scenarios
134
120
135
-
**List participants**
136
-
Returns a list of all the participants in a call. Recording and transcription bots are omitted from this list.
121
+
**List participants** – Returns a list of all the participants in a call. Recording and transcription bots are omitted from this list.
137
122
138
123
## Events
139
124
140
125
The following table outlines the current events emitted by Azure Communication Services. The following two tables describe the events emitted by Event Grid and from the Call Automation as webhook events.
141
126
142
127
### Event Grid events
143
128
144
-
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.
129
+
Most of the events sent by Event Grid are platform agnostic. They're sent regardless of the SDK (Calling or Call Automation). While you can create a subscription for any event, we recommend using 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.
145
130
146
131
| Event | Description |
147
132
| ----------------- | ------------ |
148
-
| IncomingCall | Notification of a call to a communication user or phone number |
149
-
| CallStarted |A call is established (inbound or outbound) |
150
-
| CallEnded | A call is terminated and all participants are removed|
151
-
| ParticipantAdded |A participant has been added to a call |
152
-
| ParticipantRemoved| A participant has been removed from a call |
153
-
| RecordingFileStatusUpdated| A recording file is available |
133
+
|`IncomingCall`| Notification of a call to a communication user or phone number |
134
+
|`CallStarted`|Established a call (inbound or outbound) |
135
+
|`CallEnded`| Terminated a call and removed all participants |
136
+
|`ParticipantAdded`|Added a participant to a call |
137
+
|`ParticipantRemoved`| Removed a participant from a call |
138
+
|`RecordingFileStatusUpdated`| A recording file is available |
154
139
155
-
Read more about these events and payload schema [here](../../../event-grid/communication-services-voice-video-events.md)
140
+
Read more about these events and payload schema in [Azure Communication Services - Voice and video calling events](../../../event-grid/communication-services-voice-video-events.md)
156
141
157
142
### Call Automation webhook events
158
143
@@ -185,34 +170,35 @@ The Call Automation events are sent to the web hook callback URI specified when
185
170
| SendDtmfCompleted | SendDTMF completed successfully and the DTMF tones were sent to the target participant |
186
171
| SendDtmfFailed | An error occurred while sending the DTMF tones |
187
172
188
-
To understand which events are published for different actions, refer to [this guide](../../how-tos/call-automation/actions-for-call-control.md) that provides code samples and sequence diagrams for various call control flows.
173
+
To understand which events are published for different actions, see [Actions for call control](../../how-tos/call-automation/actions-for-call-control.md). The article provides code samples and sequence diagrams for various call control flows.
189
174
190
-
When acknowledging callback events, it's best practice to respond with standard HTTP status codes like 200 OK. Detailed information is unnecessary and is more suitable for your debugging processes.
175
+
As best practice when acknowledging callback events, respond with standard HTTP status codes like **200 OK**. Detailed information is unnecessary and is more suitable for your debugging processes.
191
176
192
-
To learn how to secure the callback event delivery, refer to [this guide](../../how-tos/call-automation/secure-webhook-endpoint.md).
177
+
To learn how to secure the callback event delivery, see [How to secure webhook endpoint](../../how-tos/call-automation/secure-webhook-endpoint.md).
193
178
194
-
### Operation Callback Uri
179
+
### Operation Callback URI
195
180
196
-
It is an optional parameter in some mid-call APIs that use events as their async responses. By default, all events are sent to the default callback Uri set by CreateCall / AnswerCall API when the user establishes a call. With the usage of Operation Callback Uri, corresponding events of this individual (one-time only) request will be sent to the new Uri.
181
+
Operation Callback URI is an optional parameter in some mid-call APIs that use events as their async responses. By default, all events are sent to the default callback URI set by `CreateCall` / `AnswerCall` API events when the user establishes a call. Using the Operation Callback URI, sends corresponding events of this individual (one-time only) request to the new URI.
0 commit comments