azure-sdk/Azure.Communication.Messagesv1.3.0-beta.2
✓ Verified.NET 8.0.NET Std2.0
This client library enables working with the Microsoft Azure Communication Messages service.
Get Started
$ dotnet add package Azure.Communication.MessagesReadme
Azure Communication Messages client library for .NET
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 recipientList = new List<string> { "<RecipientPhoneNumber>" };
var textContent = new TextNotificationContent(new Guid("<channel-registration-id>"), recipientList, "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 recipientList = 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 recipientList = new List<string> { "<RecipientPhoneNumber>" };
var uri = new Uri("https://aka.ms/acsicon1");
var mediaContent = 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.