Skip to content

Commit 84355c5

Browse files
minwoolee-msftminwoolee-msft
authored
[ACS][CallAutomation] EventProcessor (Azure#34879)
* Renaming EventProcessor and Removing option * Updating CallAutomation EventProcessor based on feedbacks: - Updated name to CallAutomationEventProcessor - WaitForEvent / WaitForSingleEvent renamed to be WaitForEventProcessor to be clear that it works with EventProcessor - Async / Sync method added for all WaitForEvent - Now supports CancellationToken - Timeout to be applied with CalleationToken (See readme for detail) - Unnessary abstract base classes removed, as they confuses developer (suggestion from review) - Some EventResult will have useful infos without looking at the returned event - CallAutomationOptions's option for event processor removed as its not needed anymore - Testings updated accordingly - Readme.md updated to show how to use EventProcessor * Updated api file * Updating api --------- Co-authored-by: Min Woo Lee 🧊 <77083090+minwoolee-ms@users.noreply.github.com>
1 parent 364c30f commit 84355c5

37 files changed

+713
-330
lines changed

‎sdk/communication/Azure.Communication.CallAutomation/README.md‎

Lines changed: 114 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Install the Azure Communication CallAutomation client library for .NET with [NuG
1010

1111
```dotnetcli
1212
dotnet add package Azure.Communication.CallAutomation --prerelease
13-
```
13+
```
1414

1515
### Prerequisites
1616
You need an [Azure subscription][azure_sub] and a [Communication Service Resource][communication_resource_docs] to use this package.
@@ -22,8 +22,6 @@ To create a new Communication Service, you can use the [Azure Portal][communicat
2222

2323
### Using statements
2424
```C#
25-
using System;
26-
using System.Collections.Generic;
2725
using Azure.Communication.CallAutomation;
2826
```
2927

@@ -46,73 +44,131 @@ var client = new CallAutomationClient(endpoint, tokenCredential);
4644
### Make a call to a phone number recipient
4745
To make an outbound call, call the `CreateCall` or `CreateCallAsync` function from the `CallAutomationClient`.
4846
```C#
49-
CallSource callSource = new CallSource(
50-
new CommunicationUserIdentifier("<source-identifier>"), // Your Azure Communication Resource Guid Id used to make a Call
51-
);
52-
callSource.CallerId = new PhoneNumberIdentifier("<caller-id-phonenumber>") // E.164 formatted phone number that's associated to your Azure Communication Resource
53-
```
54-
```C#
55-
CreateCallResult createCallResult = await callAutomationClient.CreateCallAsync(
56-
source: callSource,
57-
targets: new List<CommunicationIdentifier>() { new PhoneNumberIdentifier("<targets-phone-number>") }, // E.164 formatted recipient phone number
58-
callbackEndpoint: new Uri(TestEnvironment.AppCallbackUrl)
47+
CallInvite callInvite = new CallInvite(
48+
new PhoneNumberIdentifier("<targets-phone-number>"),
49+
new PhoneNumberIdentifier("<caller-id-phonenumber>")
50+
); // E.164 formatted recipient phone number
51+
52+
// create call with above invitation
53+
createCallResult = await callAutomationClient.CreateCallAsync(
54+
callInvite,
55+
new Uri("<YOUR-CALLBACK-URL>")
5956
);
57+
6058
Console.WriteLine($"Call connection id: {createCallResult.CallConnectionProperties.CallConnectionId}");
6159
```
6260

63-
### Handle Mid-Connection call back events
64-
Your app will receive mid-connection call back events via the callbackEndpoint you provided. You will need to write event handler controller to receive the events and direct your app flow based on your business logic.
61+
### Handle Mid-Connection callback events
62+
Your app will receive mid-connection callback events via the callbackEndpoint you provided. You will need to write event handler controller to receive the events and direct your app flow based on your business logic.
6563
```C#
66-
/// <summary>
67-
/// Handle call back events.
68-
/// </summary>>
69-
[HttpPost]
70-
[Route("/CallBackEvent")]
71-
public IActionResult OnMidConnectionCallBackEvent([FromBody] CloudEvent[] events)
64+
/// <summary>
65+
/// Handle call back events.
66+
/// </summary>>
67+
[HttpPost]
68+
[Route("/CallBackEvent")]
69+
public IActionResult OnMidConnectionCallBackEvent([FromBody] CloudEvent[] events)
70+
{
71+
try
7272
{
73-
try
73+
if (events != null)
7474
{
75-
if (events != null)
75+
// Helper function to parse CloudEvent to a CallAutomation event.
76+
CallAutomationEventBase callBackEvent = CallAutomationEventParser.Parse(events.FirstOrDefault());
77+
78+
switch (callBackEvent)
7679
{
77-
// Helper function to parse CloudEvent to a CallAutomation event.
78-
CallAutomationEventBase callBackEvent = CallAutomationEventParser.Parse(events.FirstOrDefault());
79-
80-
switch (callBackEvent)
81-
{
82-
case CallConnected ev:
83-
# logic to handle a CallConnected event
84-
break;
85-
case CallDisconnected ev:
86-
# logic to handle a CallDisConnected event
87-
break;
88-
case ParticipantsUpdated ev:
89-
# cast the event into a ParticipantUpdated event and do something with it. Eg. iterate through the participants
90-
ParticipantsUpdated updatedEvent = (ParticipantsUpdated)ev;
91-
break;
92-
case AddParticipantsSucceeded ev:
93-
# logic to handle an AddParticipantsSucceeded event
94-
break;
95-
case AddParticipantsFailed ev:
96-
# logic to handle an AddParticipantsFailed event
97-
break;
98-
case CallTransferAccepted ev:
99-
# logic to handle CallTransferAccepted event
100-
break;
101-
case CallTransferFailed ev:
102-
# logic to handle CallTransferFailed event
103-
break;
104-
default:
105-
break;
106-
}
80+
case CallConnected ev:
81+
# logic to handle a CallConnected event
82+
break;
83+
case CallDisconnected ev:
84+
# logic to handle a CallDisConnected event
85+
break;
86+
case ParticipantsUpdated ev:
87+
# cast the event into a ParticipantUpdated event and do something with it. Eg. iterate through the participants
88+
ParticipantsUpdated updatedEvent = (ParticipantsUpdated)ev;
89+
break;
90+
case AddParticipantsSucceeded ev:
91+
# logic to handle an AddParticipantsSucceeded event
92+
break;
93+
case AddParticipantsFailed ev:
94+
# logic to handle an AddParticipantsFailed event
95+
break;
96+
case CallTransferAccepted ev:
97+
# logic to handle CallTransferAccepted event
98+
break;
99+
case CallTransferFailed ev:
100+
# logic to handle CallTransferFailed event
101+
break;
102+
default:
103+
break;
107104
}
108105
}
109-
catch (Exception ex)
110-
{
111-
// handle exception
112-
}
113-
return Ok();
114106
}
107+
catch (Exception ex)
108+
{
109+
// handle exception
110+
}
111+
return Ok();
112+
}
113+
```
114+
115+
### Handle Mid-Connection events with CallAutomation's EventProcessor
116+
To easily handle mid-connection events, Call Automation's SDK provides easier way to handle these events.
117+
Take a look at `CallAutomationEventProcessor`. this will ensure corelation between call and events more easily.
118+
```C#
119+
[HttpPost]
120+
[Route("/CallBackEvent")]
121+
public IActionResult OnMidConnectionCallBackEvent([FromBody] CloudEvent[] events)
122+
{
123+
try
124+
{
125+
// process incoming event for EventProcessor
126+
_callAutomationClient.GetEventProcessor().ProcessEvents(cloudEvents);
127+
}
128+
catch (Exception ex)
129+
{
130+
// handle exception
131+
}
132+
return Ok();
133+
}
134+
```
135+
`ProcessEvents` is required for EventProcessor to work.
136+
After event is being consumed by EventProcessor, you can start using its feature.
137+
138+
See below for example: where you are making a call with `CreateCall`, and wait for `CallConnected` event of the call.
139+
```C#
140+
CallInvite callInvite = new CallInvite(
141+
new PhoneNumberIdentifier("<targets-phone-number>"),
142+
new PhoneNumberIdentifier("<caller-id-phonenumber>")
143+
); // E.164 formatted recipient phone number
144+
145+
// create call with above invitation
146+
createCallResult = await callAutomationClient.CreateCallAsync(
147+
callInvite,
148+
new Uri("<YOUR-CALLBACK-URL>")
149+
);
150+
151+
// giving 30 seconds timeout for call reciever to answer
152+
CancellationTokenSource cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
153+
CancellationToken token = cts.Token;
154+
155+
try
156+
{
157+
// this will wait until CreateCall is completed or Timesout!
158+
CreateCallEventResult eventResult = await createCallResult.WaitForEventAsync(token);
159+
160+
// Once this is recieved, you know the call is now connected.
161+
CallConnected returnedEvent = eventResult.SuccessEvent;
162+
163+
// ...Do more actions, such as Play or AddParticipant, since the call is established...
164+
}
165+
catch (OperationCanceledException ex)
166+
{
167+
// Timeout exception happend!
168+
// Call likely was never answered.
169+
}
115170
```
171+
If cancellation token was not passed with timeout, the default timeout is 4 minutes.
116172

117173
## Troubleshooting
118174
A `RequestFailedException` is thrown as a service response for any unsuccessful requests. The exception contains information about what response code was returned from the service.

0 commit comments

Comments
 (0)