Azure.Communication.CallAutomation
1.0.0-beta.1
Prefix Reserved
See the version list below for details.
dotnet add package Azure.Communication.CallAutomation --version 1.0.0-beta.1
NuGet\Install-Package Azure.Communication.CallAutomation -Version 1.0.0-beta.1
<PackageReference Include="Azure.Communication.CallAutomation" Version="1.0.0-beta.1" />
paket add Azure.Communication.CallAutomation --version 1.0.0-beta.1
#r "nuget: Azure.Communication.CallAutomation, 1.0.0-beta.1"
// Install Azure.Communication.CallAutomation as a Cake Addin #addin nuget:?package=Azure.Communication.CallAutomation&version=1.0.0-beta.1&prerelease // Install Azure.Communication.CallAutomation as a Cake Tool #tool nuget:?package=Azure.Communication.CallAutomation&version=1.0.0-beta.1&prerelease
Azure Communication CallAutomation client library for .NET
This package contains a C# SDK for Azure Communication Call Automation.
Source code | Product documentation
Getting started
Install the package
Install the Azure Communication CallAutomation client library for .NET with NuGet:
dotnet add package Azure.Communication.CallAutomation --prerelease
Prerequisites
You need an Azure subscription and a Communication Service Resource to use this package.
To create a new Communication Service, you can use the Azure Portal, the Azure PowerShell, or the .NET management client library.
Key concepts
CallAutomationClient
provides the functionality to answer incoming call or initialize an outbound call.
Using statements
using System;
using System.Collections.Generic;
using Azure.Communication.CallAutomation;
Authenticate the client
Call Automation client can be authenticated using the connection string acquired from an Azure Communication Resource in the Azure Portal.
var connectionString = "<connection_string>"; // Find your Communication Services resource in the Azure portal
CallAutomationClient callAutomationClient = new CallAutomationClient(connectionString);
Or alternatively using a valid Active Directory token.
var endpoint = new Uri("https://my-resource.communication.azure.com");
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CallAutomationClient(endpoint, tokenCredential);
Examples
Make a call to a phone number recipient
To make an outbound call, call the CreateCall
or CreateCallAsync
function from the CallAutomationClient
.
CallSource callSource = new CallSource(
new CommunicationUserIdentifier("<source-identifier>"), // Your Azure Communication Resource Guid Id used to make a Call
);
callSource.CallerId = new PhoneNumberIdentifier("<caller-id-phonenumber>") // E.164 formatted phone number that's associated to your Azure Communication Resource
CreateCallResult createCallResult = await callAutomationClient.CreateCallAsync(
source: callSource,
targets: new List<CommunicationIdentifier>() { new PhoneNumberIdentifier("<targets-phone-number>") }, // E.164 formatted recipient phone number
callbackEndpoint: new Uri(TestEnvironment.AppCallbackUrl)
);
Console.WriteLine($"Call connection id: {createCallResult.CallConnectionProperties.CallConnectionId}");
Handle Mid-Connection call back events
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.
/// <summary>
/// Handle call back events.
/// </summary>>
[HttpPost]
[Route("/CallBackEvent")]
public IActionResult OnMidConnectionCallBackEvent([FromBody] CloudEvent[] events)
{
try
{
if (events != null)
{
// Helper function to parse CloudEvent to a CallAutomation event.
CallAutomationEventBase callBackEvent = CallAutomationEventParser.Parse(events.FirstOrDefault());
switch (callBackEvent)
{
case CallConnected ev:
# logic to handle a CallConnected event
break;
case CallDisconnected ev:
# logic to handle a CallDisConnected event
break;
case ParticipantsUpdated ev:
# cast the event into a ParticipantUpdated event and do something with it. Eg. iterate through the participants
ParticipantsUpdated updatedEvent = (ParticipantsUpdated)ev;
break;
case AddParticipantsSucceeded ev:
# logic to handle an AddParticipantsSucceeded event
break;
case AddParticipantsFailed ev:
# logic to handle an AddParticipantsFailed event
break;
case CallTransferAccepted ev:
# logic to handle CallTransferAccepted event
break;
case CallTransferFailed ev:
# logic to handle CallTransferFailed event
break;
default:
break;
}
}
}
catch (Exception ex)
{
// handle exception
}
return Ok();
}
Idempotent Requests
An operation is idempotent if it can be performed multiple times and have the same result as a single execution.
The following operations are idempotent:
AnswerCall
RedirectCall
RejectCall
CreateCall
HangUp
when terminating the call for everyone, ie.forEveryone
parameter is set totrue
.TransferCallToParticipant
AddParticipants
RemoveParticipants
StartRecording
By default, SDK generates a new RepeatabilityHeaders
object every time the above operation is called. If you would
like to provide your own RepeatabilityHeaders
for your application (eg. for your own retry mechanism), you can do so by specifying
the RepeatabilityHeaders
in the operation's Options
object. If this is not set by user, then the SDK will generate
it. You can also disable this by setting RepeatabilityHeaders
to NULL in the option.
The parameters for the RepeatabilityHeaders
class are repeatabilityRequestId
and repeatabilityFirstSent
. Two or
more requests are considered the same request if and only if both repeatability parameters are the same.
repeatabilityRequestId
: an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.repeatabilityFirstSent
: The value should be the date and time at which the request was first created.
To set repeatability parameters, see below C# code snippet as an example:
var createCallOptions = new CreateCallOptions(callSource, new CommunicationIdentifier[] { target }, new Uri("https://exmaple.com/callback")) {
RepeatabilityHeaders = new RepeatabilityHeaders(Guid.NewGuid(), DateTimeOffset.UtcNow);
};
CreateCallResult response1 = await callAutomationClient.CreateCallAsync(createCallOptions).ConfigureAwait(false);
await Task.Delay(5000);
CreateCallResult response2 = await callAutomationClient.CreateCallAsync(createCallOptions).ConfigureAwait(false);
// response1 and response2 will have the same CallConnectionId as they have the same reapeatability parameters which means that the CreateCall operation was only executed once.
Troubleshooting
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.
Next steps
- Call Automation Overview
- Incoming Call Concept
- Build a customer interaction workflow using Call Automation
- Redirect inbound telephony calls with Call Automation
- Quickstart: Play action
- Quickstart: Recognize action
- Read more about Call Recording in Azure Communication Services
- Record and download calls with Event Grid
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Azure.Communication.Common (>= 1.2.0)
- Azure.Core (>= 1.25.0)
- System.Text.Json (>= 4.7.2)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.3.0-beta.1 | 722 | 8/5/2024 |
1.2.0 | 14,907 | 5/1/2024 |
1.1.0 | 10,649 | 11/23/2023 |
1.1.0-beta.1 | 16,046 | 8/17/2023 |
1.0.0 | 10,121 | 6/16/2023 |
1.0.0-beta.1 | 6,698 | 11/5/2022 |