title | keywords | ms.date | ms.topic | ms.devlang | ms.service |
---|---|---|---|---|---|
Azure Communications SMS Service client library for Java |
Azure, java, SDK, API, azure-communication-sms, communication |
08/25/2024 |
reference |
java |
communication |
Azure Communication SMS is used to send simple text messages.
Source code | Package (Maven) | API reference documentation | Product documentation
- An Azure account with an active subscription. Create an account for free.
- Java Development Kit (JDK) version 8 or above.
- Apache Maven.
- A deployed Communication Services resource. You can use the Azure Portal or the Azure PowerShell to set it up.
Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. To learn more about the BOM, see the AZURE SDK BOM README.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-sdk-bom</artifactId>
<version>{bom_version_to_target}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
and then include the direct dependency in the dependencies section without the version tag.
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-sms</artifactId>
</dependency>
</dependencies>
If you want to take dependency on a particular version of the library that is not present in the BOM, add the direct dependency to your project as follows.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-sms</artifactId>
<version>1.1.27</version>
</dependency>
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";
SmsClient smsClient = new SmsClientBuilder()
.endpoint(endpoint)
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
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>");
SmsClient smsClient = new SmsClientBuilder()
.endpoint(endpoint)
.credential(azureKeyCredential)
.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>";
SmsClient smsClient = new SmsClientBuilder()
.connectionString(connectionString)
.buildClient();
There are two different forms of authentication to use the Azure Communication SMS Service.
Use the send
or sendWithResponse
function to send an 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());
To send an 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());
}
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());
}
- Read more about SMS in Azure Communication Services
- For a basic guide on how to configure Delivery Reporting for your SMS messages please refer to the Handle SMS Events quickstart.
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.