Announcing the new Azure Communication Services Libraries GA

Jorge Garcia Hirota

Today, we’re excited to announce that the Azure Communication Services is generally available. Developers can now add chat, voice calling, video calling, traditional telephone calling, SMS messaging, and other forms of real-time communication to their applications using the same technology that powers Microsoft Teams. Interoperability with Microsoft Teams is also supported (public preview).

We recently showcased Azure Communication Services at Microsoft Ignite. To see how these services work together, you can watch our feature sessions here:

• Ignite On-Demand: Accelerating digital customer engagement with Azure Communication Services
• Ignite Ask the Experts: Accelerating digital customer engagement with Azure Communication Services
• Microsoft Mechanics: Azure Communication Services Updates

SDK Availability

The Azure Communication Services development experience is divided into several composable client libraries that support a wide array of platforms and languages:

**All mobile SDKs (Android and iOS) are under public preview mode.*

**Phone numbers SDKs (JavaScript/TypeScript, .NET, Python, & Java) are under public preview mode.

Identity

You can create identities with the Azure Communication Services Identity library and assign them to your users. An identity serves as an identifier in conversations and is used to create access tokens. The same identity can participate in multiple simultaneous sessions across multiple devices. An identity can also have multiple active access tokens at the same time.

The Identity library is only used by Calling features and Chat features.

Key concepts

CommunicationIdentityClient is used to create user identities and to create and revoke tokens associated with those identities. There are currently three ways to create it (CommunicationIdentityClient):

The identity client can be authenticated using a connection string acquired from an Azure Communication Resources in the Azure Portal.

// Get a connection string to our Azure Communication resource. 
var connectionString = ""; 
var client = new CommunicationIdentityClient(connectionString);

The endpoint and access key acquired from an Azure Communication Resources in the Azure Portal can be used:

var endpoint = new Uri("https://my-resource.communication.azure.com");
var accessKey = "<access_key>";
var client = new CommunicationIdentityClient(endpoint, new AzureKeyCredential(accessKey));

Clients can authenticate using a valid Active Directory token via Azure.Identity:

var endpoint = new Uri("https://my-resource.communication.azure.com"); 
TokenCredential tokenCredential = new DefaultAzureCredential(); 
var client = new CommunicationIdentityClient(endpoint, tokenCredential);

Once you define your client you can also create users and tokens.

Also, you will need the scope parameter; this parameter defines a nonempty set of primitives that can be used. Azure Communication Services supports the following scopes for access tokens.

• Chat: Grants the ability to participate in a chat
• VoIP: Grants the ability to call identities and phone numbers

Creating a new user

Response<communicationuseridentifier> userResponse = await client.CreateUserAsync();
CommunicationUserIdentifier user = userResponse.Value;

Getting a token for an existing user

Response<accesstoken> tokenResponse = await client.GetTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;

Creating a user and a token in the same request

Response<communicationuseridentifierandtoken> response = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.Chat });

Revoking a user’s tokens

In case a user’s tokens are compromised or need to be revoked you can revoke all tokens issued to that user.

Response revokeResponse = client.RevokeTokens(user);

Visit the “Use Managed Identities” site to find more details.

SMS

Azure Communication Services enables you to send and receive SMS text messages using the Communication Services SMS client libraries. These client libraries can be used to support customer service scenarios, appointment reminders, two-factor authentication, and other real-time communication needs. Communication Services SMS allows you to reliably send messages while exposing deliverability and response rate insights surrounding your campaigns.

• Simple setup experience for adding SMS capability to your applications.
• High Velocity message support over toll free numbers for A2P (Application to Person) use cases in the United States.
• Two-way conversations to support scenarios like customer support, alerts, and appointment reminders.
• Reliable Delivery with real-time delivery reports for messages sent from your application.
• Opt-Out handling support to automatically detect and respect opt-outs for toll-free numbers. Opt-outs for US toll-free numbers are mandated and enforced by US carriers.

Key concepts

SmsClient provides the functionality to send messages among phone numbers. SmsClient can be authenticated using the connection string and also be authenticated using a valid token credential; you can review the options that we listed before under Identity section.

string endpoint = "<endpoint_url>";
TokenCredential tokenCredential = new DefaultAzureCredential();
SmsClient smsClient = new SmsClient(new Uri(endpoint), tokenCredential);
    
SmsSendResult sendResult = smsClient.Send(
    from: "<from-phone-number>", // Your E.164 formatted from phone number used to send SMS
    to: "<to-phone-number>", // E.164 formatted recipient phone number
    message: "Hello World via SMS"
);

You should replace <from-phone-number> with an SMS-enabled phone number associated with your Communication Services resource and <to-phone-number> with the phone number you wish to send a message to.

Visit the SMS SDK site to find more details.

Phone numbers

Azure Communication Services allows you to use phone numbers to make voice calls and send SMS messages with the public-switched telephone network (PSTN). If your phone number will be used by an application (for example, to make calls or send messages on behalf of your organization), you can select a toll-free or local (geographic) number. If your phone number is being used by a person (for example, a user of your calling application), the local (geographic) phone number must be used. You can review more details in our “Phone Numbers” documentation site.

Key concepts

Phone numbers can be searched through the search creation API by providing an area code, application type, phone number type, and capabilities. The phone number(s) in the search result will be reserved for ten minutes during which you can purchase them; otherwise, they will be released automatically. If the search is not purchased, the phone numbers will become available to others after ten minutes. The phone numbers found through the search operation could be acquired for the Azure resource and used by other communication services.

The initial step is creating a PhoneNumbersClient to start interacting with the phone numbers. To create a new PhoneNumbersClient you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource.

Phone numbers need to be searched before they can be purchased. Search is a long running operation that can be started byStartSearchAvailablePhoneNumbers function that returns an SearchAvailablePhoneNumbersOperation object.SearchAvailablePhoneNumbersOperation can be used to update status of the operation and to check for completeness.

To create a client, you can use any of the suggested Identity options that we listed before; for this example, we use via a connection string. You can set a connection string based on an environment variable, a configuration setting, or any way that works for your application.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);

var capabilities = new PhoneNumberCapabilities(calling:PhoneNumberCapabilityType.None, sms:PhoneNumberCapabilityType.Outbound);

var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync(countryCode, PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities);
await searchOperation.WaitForCompletionAsync();

var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();

Visit the “Telephony Concepts” site to find more details.

Calling

You can use Azure Communication Services Calling client library to make and receive one-to-one or group voice and video calls. Your calls can be made to other users of your Azure Communication Services enabled app or website, and to PSTN telephones such as mobile phones. You can use the Communication Services JavaScript, Android, or iOS client libraries to build applications that allow your users to speak to one another in private conversations or in group discussions. Azure Communication Services supports calls to and from services or Bots.

There are two separate families of Calling client libraries, for clients and services. Currently available client libraries are intended for end-user experiences: websites and native apps.

Calling client library capabilities

The calling client libraries support the following capabilities:

JavaScript calling client library support by OS and browser

Azure Communication Services client libraries support the following browsers:

Visit the Calling SDK site to get more details.

Chat

Azure Communication Services Chat client library can be used to add real-time text chat to your applications.

Key concepts

A chat conversation is represented by a chat thread. Each user in the chat thread is called a thread participant and is backed by a communication user created through the Azure Communication Identity package. Thread participants can chat with one another privately in a 1:1 chat or huddle up in a 1:N group chat. Users also get near-real time updates for when others are typing and when they have read the messages.

Create a ChatClient

This will allow you to create, get, or delete chat threads.

To authenticated in the ChatClient, you will need to authenticate by the user that is intended to send and receive messages. The user and its token can be created using the Azure Communication Identity package (you can review the options that we listed before Identity section).

ChatClient chatClient = new ChatClient(
    endpoint,
    new CommunicationTokenCredential(userToken));

Once you initialize a ChatClient class, you can perform chat operations:

Create a chat thread

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<user_id>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Once you initialized a ChatThreadClient class, you can do the following chat operations:

Send a message

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(content:"hello world", type: ChatMessageType.Text);
string messageId = sendChatMessageResult.Id;

Receive chat messages from a chat thread

AsyncPageable<chatmessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Add participants

var josh= new CommunicationUserIdentifier(id: "<user_id_for_josh>");
var gloria = new CommunicationUserIdentifier(id: "<user_id_for_gloria>");
var amy = new CommunicationUserIdentifier(id: "<user_id_for_amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

Visit the Chat SDK site to find more details.

Conclusion

We hope this was a valuable technical introduction to Azure Communication Services and what you can use today to build and ship rich communication experiences.

If you want to learn more and get started, here are some quick links to our official documentation:

• .NET
• Java
• Python
• JavaScript/TypeScript
• Android
• iOS

References

• Official documentation
• Create your first resource
• Release notes

Azure SDK Blog Contributions

Thank you for reading this Azure SDK blog post! We hope that you learned something new and welcome you to share this post. We are open to Azure SDK blog contributions. Please contact us at azsdkblog@microsoft.com with your topic and we’ll get you set up as a guest blogger.

Azure SDK Links

• Azure SDK Website: aka.ms/azsdk
• Azure SDK Intro (3 minute video): aka.ms/azsdk/intro
• Azure SDK Intro Deck (PowerPoint deck): aka.ms/azsdk/intro/deck
• Azure SDK Releases: aka.ms/azsdk/releases
• Azure SDK Blog: aka.ms/azsdk/blog
• Azure SDK Twitter: twitter.com/AzureSDK
• Azure SDK Design Guidelines: aka.ms/azsdk/guide
• Azure SDKs & Tools: azure.microsoft.com/downloads
• Azure SDK Central Repository: github.com/azure/azure-sdk
• Azure SDK for .NET: github.com/azure/azure-sdk-for-net
• Azure SDK for Java: github.com/azure/azure-sdk-for-java
• Azure SDK for Python: github.com/azure/azure-sdk-for-python
• Azure SDK for JavaScript/TypeScript: github.com/azure/azure-sdk-for-js
• Azure SDK for Android: github.com/Azure/azure-sdk-for-android
• Azure SDK for iOS: github.com/Azure/azure-sdk-for-ios
• Azure SDK for Go: github.com/Azure/azure-sdk-for-go
• Azure SDK for C: github.com/Azure/azure-sdk-for-c
• Azure SDK for C++: github.com/Azure/azure-sdk-for-cpp

Jorge Garcia Hirota Program Manager, Azure Communication Services

Follow