Edit

Share via

Handle events with the Call Automation event processor

After a call is established with Call Automation, a further update of the ongoing call is sent as a separate event via a webhook callback. These events have important information, such as the latest state of the call and the outcome of the request that was sent.

The Call Automation event processor helps to easily process webhook callback events for your applications. It helps to correlate each event to its respective call so that you can build applications with ease.

Benefits

By using event processor features, you can easily build robust applications that can handle Call Automation events. They can:

  • Associate an event to its respective calls.
  • Write code linearly.
  • Handle events that could happen anytime during the call (such as CallDisconnected or ParticipantsUpdated).
  • Handle rare cases where events arrive earlier than the request's response.
  • Set a custom timeout for waiting on events.

Pass events to the Call Automation event processor

The Call Automation event processor first needs to consume events that were sent from the service. After the event arrives at the callback endpoint, pass the event to the event processor.

Important

Have you established a webhook callback events endpoint? The event processor still needs to consume callback events through a webhook callback. For information on how to establish webhook endpoints, see Make an outbound call by using Call Automation.

using Azure.Communication.CallAutomation;

[HttpPost]
public IActionResult CallbackEvent([FromBody] CloudEvent[] cloudEvents)
{
    // Use your call automation client that established the call
    CallAutomationEventProcessor eventProcessor = callAutomationClient.GetEventProcessor();

    // Let event be processed in EventProcessor
    eventProcessor.ProcessEvents(cloudEvents);
    return Ok();
}

Now you're ready to use the event processor.

Use the Create Call request response to wait for a Call Connected event

The first scenario is to create an outbound call and then wait until the call is established with the event processor.

// Creating an outbound call here
CreateCallResult createCallResult = await callAutomationClient.CreateCallAsync(callInvite, callbackUri);
CallConnection callConnection = createCallResult.CallConnection;

// Wait for 40 seconds before throwing timeout error.
var tokenSource = new CancellationTokenSource(TimeSpan.FromSeconds(40));

// We can wait for EventProcessor that related to outbound call here. In this case, we are waiting for CreateCallEventResult, up to 40 seconds.
CreateCallEventResult eventResult = await createCallResult.WaitForEventProcessorAsync(tokenSource);

// Once EventResult comes back, we can get SuccessResult of CreateCall - which is, CallConnected event.
CallConnected returnedEvent = eventResult.SuccessResult;

With the event processor, you can easily wait for the CallConnected event until the call is established. If the call was never established (that is, the caller never picked up the phone), it throws a timeout exception. If the creation of the call otherwise fails, you receive CallDisconnected and CreateCallFailed events with error codes for further troubleshooting. For more information on Call Automation error codes, see Troubleshooting call end response codes.

If a specific timeout wasn't given when you waited on the event processor, it waits until its default timeout happens. The default timeout is four minutes.

Use the Play request response to wait for Play events

Now that the call is established, try to play some audio in the call, and then wait until the media plays.

// Play my prompt to everyone.
FileSource fileSource = new FileSource(playPrompt);
PlayResult playResult = await callConnection.GetCallMedia().PlayToAllAsync(fileSource);

// Wait for play to complete.
PlayEventResult playEventResult = await playResult.WaitForEventProcessorAsync();

// Check if the play was completed successfully.
if (playEventResult.IsSuccess)
{
    // Success play!
    PlayCompleted playCompleted = playEventResult.SuccessResult;
}
else
{
    // Failed to play the audio.
    PlayFailed playFailed = playEventResultResult.FailureResult;
}

Warning

The event processor uses OperationContext to track an event with its related request. If OperationContext wasn't set during the request, the event processor sets generated GUID to track future events to the request. If you set OperationContext during the request, the event processor still works, but we recommend that you set them differently from request to request. In this way, the event processor can distinguish the first request's event and the second request's event.

Handle events with the ongoing event processor

Some events could happen anytime during the call, such as CallDisconnected or ParticipantsUpdated, when other callers leave the call. The event processor provides a way to handle these events easily with the ongoing event handler.

// Use your call automation client that established the call
CallAutomationEventProcessor eventProcessor = callAutomationClient.GetEventProcessor();

// attach ongoing EventProcessor for this particular call,
// then prints out # of participants in the call
eventProcessor.AttachOngoingEventProcessor<ParticipantsUpdated>(callConnectionId, receivedEvent => {
    logger.LogInformation($"Number of participants in this Call: [{callConnectionId}], Number Of Participants[{receivedEvent.Participants.Count}]");
});

With this specific ongoing event processor, you can now print the number of participants or the participants on the call whenever people join or leave the call.

You can attach an ongoing handler to any event type. This capability opens the possibility to build your application with a callback design pattern.

Advanced: Use a predicate to wait for a specific event

If you want to wait for a specific event with a specific predicate without the need to rely on EventResult returned from the request, it's also possible to do so with a predicate. Try to wait for a CallDisconnected event with the matching CallConnectionId and its type.

// Use your call automation client that established the call
CallAutomationEventProcessor eventProcessor = callAutomationClient.GetEventProcessor();

// With given matching information, wait for this specific event
CallDisconnected disconnectedEvent = (CallDisconnected)await eventProcessor.WaitForEvent(predicate
=>
    predicate.CallConnectionId == myConnectionId
    && predicate.GetType() == typeof(CallDisconnected)
);

Advanced: Detailed specifications

  • The default timeout for waiting on the event processor is four minutes. After that, it throws a timeout exception.
  • The same call automation client that made the request must be used to wait on an event by using the event processor.
  • After the CallDisconnect event is received for the call, all the call's events are removed from the memory.
  • In some rare cases, an event might arrive earlier than the response of the request. In these cases, it's saved in backlog for five seconds.
  • You might have multiple event processors waiting on the same event. After the matching event arrives, all the event processors waiting on that event return with the arrived event.

Related content

  • Last updated on