This client library enables working with the Microsoft Azure Communication Sms service.
For this release, see notes - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Sms/README.md and https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Sms/CHANGELOG.md.
Microsoft Azure Communication Sms quickstart - https://docs.microsoft.com/azure/communication-services/quickstarts/telephony-sms/send?pivots=programming-language-csharp
SmsClient provides the functionality to send messages between phone numbers.
Using statements
using System;
using Azure.Communication.Sms;
Authenticate the client
SMS clients 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
SmsClient client = new SmsClient(connectionString);
Alternatively, SMS clients can also be authenticated using a valid token credential. With this option,
, and environment variables need to be set up for authentication.
AZURE_CLIENT_SECRET
AZURE_CLIENT_ID
AZURE_TENANT_ID
string endpoint = "<endpoint_url>";
TokenCredential tokenCredential = new DefaultAzureCredential();
SmsClient client = new SmsClient(new Uri(endpoint), tokenCredential);
Examples
SMS
Send a 1:1 SMS Message
To send a SMS message, call the Send or SendAsync function from the SmsClient.
SmsSendResult sendResult = await smsClient.SendAsync(
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: "Hi");
Console.WriteLine($"Sms id: {sendResult.MessageId}");
Send a 1:N SMS Message
To send a SMS message to a list of recipients, call the Send or SendAsync function from the SmsClient with a list of recipient's phone numbers.
You can also provide an options object to configure various settings, such as enabling the delivery report, adding custom tags, or specifying parameters for connecting with the Messaging Connect Partner to deliver SMS.
var response = await smsClient.SendAsync(
from: "<from-phone-number>", // Your E.164 formatted from phone number used to send SMS
to: new string[] { "<to-phone-number-1>", "<to-phone-number-2>" }, // E.164 formatted recipient phone numbers
message: "Weekly Promotion!",
options: new SmsSendOptions(enableDeliveryReport: true) // OPTIONAL
{
Tag = "marketing", // custom tags
DeliveryReportTimeoutInSeconds = 90
});
foreach (SmsSendResult result in response.Value)
{
Console.WriteLine($"Sms id: {result.MessageId}");
Console.WriteLine($"Send Result Successful: {result.Successful}");
}
Opt Out Management
Check if a list of recipients is in the Opt Out list
To check if the recipients are in the Opt Out list, call the function from the SmsClient.OptOuts.Check or SmsClient.OptOuts.CheckAsync with a list of recipient phone numbers.
var optOutCheckResults = await smsClient.OptOuts.CheckAsync(
from: "<from-phone-number>", // Your E.164 formatted from phone number used to send SMS
to: new string[] { "<to-phone-number-1>", "<to-phone-number-2>" }); // E.164 formatted recipient phone numbers
foreach (var result in optOutCheckResults.Value)
{
Console.WriteLine($"{result.To}: {result.IsOptedOut}");
}
Add a list of recipients to Opt Out list
To add the list of recipients to Opt Out list, call the function from the SmsClient.OptOuts.Add or SmsClient.OptOuts.AddAsync with a list of recipient phone numbers.
var optOutAddResults = await smsClient.OptOuts.AddAsync(
from: "<from-phone-number>", // Your E.164 formatted from phone number used to send SMS
to: new string[] { "<to-phone-number-1>", "<to-phone-number-2>" }); // E.164 formatted recipient phone numbers
foreach (var result in optOutAddResults.Value)
{
Console.WriteLine($"{result.To}: {result.HttpStatusCode}");
}
Remove a list of recipients from Opt Out list
To remove the list of recipients to Opt Out list, call the function from the SmsClient.OptOuts.Remove or SmsClient.OptOuts.RemoveAsync with a list of recipient phone numbers.
var optOutRemoveResults = await smsClient.OptOuts.RemoveAsync(
from: "<from-phone-number>", // Your E.164 formatted from phone number used to send SMS
to: new string[] { "<to-phone-number-1>", "<to-phone-number-2>" }); // E.164 formatted recipient phone numbers
foreach (var result in optOutRemoveResults.Value)
{
Console.WriteLine($"{result.To}: {result.HttpStatusCode}");
}
Troubleshooting
SMS operations will throw an exception if the request to the server fails.
Exceptions will not be thrown if the error is caused by an individual message, only if something fails with the overall request.
Please use the Successful flag to validate each individual result to verify if the message was sent.
try
{
var response = await smsClient.SendAsync(
from: "<from-phone-number>" // Your E.164 formatted phone number used to send SMS
to: new string [] {"<to-phone-number-1>", "<to-phone-number-2>"}, // E.164 formatted recipient phone number
message: "Weekly Promotion!",
options: new SmsSendOptions(enableDeliveryReport: true) // OPTIONAL
{
Tag = "marketing", // custom tags
});
foreach (SmsSendResult result in response.Value)
{
if (result.Successful)
{
Console.WriteLine($"Successfully sent this message: {result.MessageId} to {result.To}.");
}
else
{
Console.WriteLine($"Something went wrong when trying to send this message {result.MessageId} to {result.To}.");
Console.WriteLine($"Status code {result.HttpStatusCode} and error message {result.ErrorMessage}.");
}
}
}
catch (RequestFailedException ex)
{
Console.WriteLine(ex.Message);
}
For a basic guide on how to configure Delivery Reporting for your SMS messages please refer to the Handle SMS Events quickstart.
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.