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.CallingServer --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.CallingServer;

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 CallingServer event.
                CallAutomationEventBase callBackEvent = EventParser.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();
    }

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

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.