Azure Communications SMS Service client library for Java - version 1.0.0-beta.4

  • Article

Azure Communication SMS is used to send simple text messages.

Source code | Package (Maven) | API reference documentation | Product documentation

Getting started

Prerequisites

Include the package

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-sms</artifactId>
  <version>1.0.0-beta.4</version>
</dependency>

Authenticate the client

Azure Active Directory Token Authentication

A DefaultAzureCredential object must be passed to the SmsClientBuilder via the credential() function. Endpoint and httpClient must also be set via the endpoint() and httpClient() functions respectively.

AZURE_CLIENT_SECRET, AZURE_CLIENT_ID and AZURE_TENANT_ID environment variables are needed to create a DefaultAzureCredential object.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SmsClient smsClient = new SmsClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

Access Key Authentication

SMS uses HMAC authentication with the resource access key. The access key must be provided to the SmsClientBuilder via the credential() function. Endpoint and httpClient must also be set via the endpoint() and httpClient() functions respectively.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<resource-name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access-key>");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SmsClient smsClient = new SmsClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .httpClient(httpClient)
    .buildClient();

Alternatively, you can provide the entire connection string using the connectionString() function instead of providing the endpoint and access key.

// You can find your connection string from your resource in the Azure Portal
String connectionString = "https://<resource-name>.communication.azure.com/;<access-key>";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SmsClient smsClient = new SmsClientBuilder()
    .connectionString(connectionString)
    .httpClient(httpClient)
    .buildClient();

Key concepts

There are two different forms of authentication to use the Azure Communication SMS Service.

Examples

Send a 1:1 SMS Message

Use the send or sendWithResponse function to send a SMS message to a single phone number.

SmsSendResult sendResult = smsClient.send(
    "<from-phone-number>",
    "<to-phone-number>",
    "Weekly Promotion");

System.out.println("Message Id: " + sendResult.getMessageId());
System.out.println("Recipient Number: " + sendResult.getTo());
System.out.println("Send Result Successful:" + sendResult.isSuccessful());

Send a 1:N SMS Message

To send a SMS message to a list of recipients, call the send or sendWithResponse function with a list of recipient phone numbers. You may also add pass in an options object to specify whether the delivery report should be enabled and set custom tags.

SmsSendOptions options = new SmsSendOptions();
options.setDeliveryReportEnabled(true);
options.setTag("Marketing");

Iterable<SmsSendResult> sendResults = smsClient.sendWithResponse(
    "<from-phone-number>",
    Arrays.asList("<to-phone-number1>", "<to-phone-number2>"),
    "Weekly Promotion",
    options /* Optional */,
    Context.NONE).getValue();

for (SmsSendResult result : sendResults) {
    System.out.println("Message Id: " + result.getMessageId());
    System.out.println("Recipient Number: " + result.getTo());
    System.out.println("Send Result Successful:" + result.isSuccessful());
}

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 isSuccessful() flag to validate each individual result to verify if the message was sent.

try {
    SmsSendOptions options = new SmsSendOptions();
    options.setDeliveryReportEnabled(true);
    options.setTag("Marketing");

    Response<Iterable<SmsSendResult>> sendResults = smsClient.sendWithResponse(
        "<from-phone-number>",
        Arrays.asList("<to-phone-number1>", "<to-phone-number2>"),
        "Weekly Promotion",
        options /* Optional */,
        Context.NONE);

    Iterable<SmsSendResult> smsSendResults = sendResults.getValue();
    for (SmsSendResult result : smsSendResults) {
        if (result.isSuccessful()) {
            System.out.println("Successfully sent this message: " + result.getMessageId() + " to " + result.getTo());
        } else {
            System.out.println("Something went wrong when trying to send this message " + result.getMessageId() + " to " + result.getTo());
            System.out.println("Status code " + result.getHttpStatusCode() + " and error message " + result.getErrorMessage());
        }
    }
} catch (RuntimeException ex) {
    System.out.println(ex.getMessage());
}

Next steps

Check out other client libraries for Azure Communication Services

Impressions

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.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

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.