Azure Communication Messages client library for .NET - version 1.1.0

This package contains a C# SDK for Azure Communication Messages Services.

Source code | Package (NuGet) | Product documentation

Getting started

Install the package

Install the Azure Communication Messages client library for .NET with NuGet:

dotnet add package Azure.Communication.Messages

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.

You must register your WhatsApp business account and have an active channel before sending messages. See Quickstart: Register WhatsApp business account for more details

Key concepts

NotificationMessagesClient provides the functionality to send notification messages.

Using statements

using Azure.Communication.Messages;

Authenticate the client

Connection string

The NotificationMessagesClient is used for sending messages. The MessageTemplateClient is used for retrieving template information.

For simplicity, this example uses a connection string to authenticate. In production environments, we recommend using Microsoft Entra ID.

Messages clients can be authenticated using the connection string acquired from an Azure Communication Resource in the Azure Portal.

var connectionString = "<ConnectionString>"; // Find your Communication Services resource in the Azure portal
NotificationMessagesClient notificationMessagesClient = new NotificationMessagesClient(connectionString);
MessageTemplateClient messageTemplateClient = new MessageTemplateClient(connectionString);

Examples

Send a notification message

To send a notification message, call the Send or SendAsync function from the NotificationMessagesClient.

Send a text message

// Create the recipient list, currently only one recipient is supported 
var recipient = new List<string> { "<RecipientPhoneNumber>" };
var textContent = new = new TextNotificationContent(new Guid("<channel-registration-id>"), recipient, "Come on everyone, let's go for lunch together.");
SendMessageResult result = await notificationMessagesClient.SendAsync(textContent);
Console.WriteLine($"Message id: {result.Receipts[0].MessageId}");

Send a template message

// Create the recipient list, currently only one recipient is supported 
var recipient = new List<string> { "<RecipientPhoneNumber>" };
string templateName = "sample_template";
string templateLanguage = "en_us";
var messageTemplate = new MessageTemplate(templateName, templateLanguage);
var templateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplate);
SendMessageResult result = await notificationMessagesClient.SendAsync(templateContent);
Console.WriteLine($"Message id: {result.Receipts[0].MessageId}");

Send a media message

// Create the recipient list, currently only one recipient is supported 
var recipient = new List<string> { "<RecipientPhoneNumber>" };
var uri = new Uri("https://aka.ms/acsicon1");
var imageContent = new ImageNotificationContent(channelRegistrationId, recipientList, uri);
SendMessageResult result = await notificationMessagesClient.SendAsync(mediaContent);
Console.WriteLine($"Message id: {result.Receipts[0].MessageId}");

Retrieve templates

To retrieve templates, call the GetTemplates or GetTemplatesAsync function from the MessageTemplateClient.

AsyncPageable<MessageTemplateItem> templates = messageTemplateClient.GetTemplatesAsync(channelId);
await foreach (MessageTemplateItem template in templates)
{
    Console.WriteLine($"{template.Name}");
}

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

• Read more about Messages in Azure Communication Services at Advanced Messaging for WhatsApp in Azure Communication Services.
• Read more about how to set up an Event Grid subscription to receive messages and message delivery statuses at Quickstart: Handle Advanced Messaging events.
• Read more about how to use templates at Send WhatsApp template messages.
• For a set-by-step guide on how to use the Messages APIs, see Quickstart: Send WhatsApp Messages using Advanced Messages].

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.