Azure Communication Sms Java

1---
2name: azure-communication-sms-java
3description: Send SMS messages with Azure Communication Services SMS Java SDK. Use when implementing SMS notifications, alerts, OTP delivery, bulk messaging, or delivery reports.
4package: com.azure:azure-communication-sms
5---
6 
7# Azure Communication SMS (Java)
8 
9Send SMS messages to single or multiple recipients with delivery reporting.
10 
11## Installation
12 
13```xml
14<dependency>
15    <groupId>com.azure</groupId>
16    <artifactId>azure-communication-sms</artifactId>
17    <version>1.2.0</version>
18</dependency>
19```
20 
21## Client Creation
22 
23```java
24import com.azure.communication.sms.SmsClient;
25import com.azure.communication.sms.SmsClientBuilder;
26import com.azure.identity.DefaultAzureCredentialBuilder;
27 
28// With DefaultAzureCredential (recommended)
29SmsClient smsClient = new SmsClientBuilder()
30    .endpoint("https://<resource>.communication.azure.com")
31    .credential(new DefaultAzureCredentialBuilder().build())
32    .buildClient();
33 
34// With connection string
35SmsClient smsClient = new SmsClientBuilder()
36    .connectionString("<connection-string>")
37    .buildClient();
38 
39// With AzureKeyCredential
40import com.azure.core.credential.AzureKeyCredential;
41 
42SmsClient smsClient = new SmsClientBuilder()
43    .endpoint("https://<resource>.communication.azure.com")
44    .credential(new AzureKeyCredential("<access-key>"))
45    .buildClient();
46 
47// Async client
48SmsAsyncClient smsAsyncClient = new SmsClientBuilder()
49    .connectionString("<connection-string>")
50    .buildAsyncClient();
51```
52 
53## Send SMS to Single Recipient
54 
55```java
56import com.azure.communication.sms.models.SmsSendResult;
57 
58// Simple send
59SmsSendResult result = smsClient.send(
60    "+14255550100",      // From (your ACS phone number)
61    "+14255551234",      // To
62    "Your verification code is 123456");
63 
64System.out.println("Message ID: " + result.getMessageId());
65System.out.println("To: " + result.getTo());
66System.out.println("Success: " + result.isSuccessful());
67 
68if (!result.isSuccessful()) {
69    System.out.println("Error: " + result.getErrorMessage());
70    System.out.println("Status: " + result.getHttpStatusCode());
71}
72```
73 
74## Send SMS to Multiple Recipients
75 
76```java
77import com.azure.communication.sms.models.SmsSendOptions;
78import java.util.Arrays;
79import java.util.List;
80 
81List<String> recipients = Arrays.asList(
82    "+14255551111",
83    "+14255552222",
84    "+14255553333"
85);
86 
87// With options
88SmsSendOptions options = new SmsSendOptions()
89    .setDeliveryReportEnabled(true)
90    .setTag("marketing-campaign-001");
91 
92Iterable<SmsSendResult> results = smsClient.sendWithResponse(
93    "+14255550100",      // From
94    recipients,          // To list
95    "Flash sale! 50% off today only.",
96    options,
97    Context.NONE
98).getValue();
99 
100for (SmsSendResult result : results) {
101    if (result.isSuccessful()) {
102        System.out.println("Sent to " + result.getTo() + ": " + result.getMessageId());
103    } else {
104        System.out.println("Failed to " + result.getTo() + ": " + result.getErrorMessage());
105    }
106}
107```
108 
109## Send Options
110 
111```java
112SmsSendOptions options = new SmsSendOptions();
113 
114// Enable delivery reports (sent via Event Grid)
115options.setDeliveryReportEnabled(true);
116 
117// Add custom tag for tracking
118options.setTag("order-confirmation-12345");
119```
120 
121## Response Handling
122 
123```java
124import com.azure.core.http.rest.Response;
125 
126Response<Iterable<SmsSendResult>> response = smsClient.sendWithResponse(
127    "+14255550100",
128    Arrays.asList("+14255551234"),
129    "Hello!",
130    new SmsSendOptions().setDeliveryReportEnabled(true),
131    Context.NONE
132);
133 
134// Check HTTP response
135System.out.println("Status code: " + response.getStatusCode());
136System.out.println("Headers: " + response.getHeaders());
137 
138// Process results
139for (SmsSendResult result : response.getValue()) {
140    System.out.println("Message ID: " + result.getMessageId());
141    System.out.println("Successful: " + result.isSuccessful());
142    
143    if (!result.isSuccessful()) {
144        System.out.println("HTTP Status: " + result.getHttpStatusCode());
145        System.out.println("Error: " + result.getErrorMessage());
146    }
147}
148```
149 
150## Async Operations
151 
152```java
153import reactor.core.publisher.Mono;
154 
155SmsAsyncClient asyncClient = new SmsClientBuilder()
156    .connectionString("<connection-string>")
157    .buildAsyncClient();
158 
159// Send single message
160asyncClient.send("+14255550100", "+14255551234", "Async message!")
161    .subscribe(
162        result -> System.out.println("Sent: " + result.getMessageId()),
163        error -> System.out.println("Error: " + error.getMessage())
164    );
165 
166// Send to multiple with options
167SmsSendOptions options = new SmsSendOptions()
168    .setDeliveryReportEnabled(true);
169 
170asyncClient.sendWithResponse(
171    "+14255550100",
172    Arrays.asList("+14255551111", "+14255552222"),
173    "Bulk async message",
174    options)
175    .subscribe(response -> {
176        for (SmsSendResult result : response.getValue()) {
177            System.out.println("Result: " + result.getTo() + " - " + result.isSuccessful());
178        }
179    });
180```
181 
182## Error Handling
183 
184```java
185import com.azure.core.exception.HttpResponseException;
186 
187try {
188    SmsSendResult result = smsClient.send(
189        "+14255550100",
190        "+14255551234",
191        "Test message"
192    );
193    
194    // Individual message errors don't throw exceptions
195    if (!result.isSuccessful()) {
196        handleMessageError(result);
197    }
198    
199} catch (HttpResponseException e) {
200    // Request-level failures (auth, network, etc.)
201    System.out.println("Request failed: " + e.getMessage());
202    System.out.println("Status: " + e.getResponse().getStatusCode());
203} catch (RuntimeException e) {
204    System.out.println("Unexpected error: " + e.getMessage());
205}
206 
207private void handleMessageError(SmsSendResult result) {
208    int status = result.getHttpStatusCode();
209    String error = result.getErrorMessage();
210    
211    if (status == 400) {
212        System.out.println("Invalid phone number: " + result.getTo());
213    } else if (status == 429) {
214        System.out.println("Rate limited - retry later");
215    } else {
216        System.out.println("Error " + status + ": " + error);
217    }
218}
219```
220 
221## Delivery Reports
222 
223Delivery reports are sent via Azure Event Grid. Configure an Event Grid subscription for your ACS resource.
224 
225```java
226// Event Grid webhook handler (in your endpoint)
227public void handleDeliveryReport(String eventJson) {
228    // Parse Event Grid event
229    // Event type: Microsoft.Communication.SMSDeliveryReportReceived
230    
231    // Event data contains:
232    // - messageId: correlates to SmsSendResult.getMessageId()
233    // - from: sender number
234    // - to: recipient number
235    // - deliveryStatus: "Delivered", "Failed", etc.
236    // - deliveryStatusDetails: detailed status
237    // - receivedTimestamp: when status was received
238    // - tag: your custom tag from SmsSendOptions
239}
240```
241 
242## SmsSendResult Properties
243 
244| Property | Type | Description |
245|----------|------|-------------|
246| `getMessageId()` | String | Unique message identifier |
247| `getTo()` | String | Recipient phone number |
248| `isSuccessful()` | boolean | Whether send succeeded |
249| `getHttpStatusCode()` | int | HTTP status for this recipient |
250| `getErrorMessage()` | String | Error details if failed |
251| `getRepeatabilityResult()` | RepeatabilityResult | Idempotency result |
252 
253## Environment Variables
254 
255```bash
256AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com
257AZURE_COMMUNICATION_CONNECTION_STRING=endpoint=https://...;accesskey=...
258SMS_FROM_NUMBER=+14255550100
259```
260 
261## Best Practices
262 
2631. **Phone Number Format** - Use E.164 format: `+[country code][number]`
2642. **Delivery Reports** - Enable for critical messages (OTP, alerts)
2653. **Tagging** - Use tags to correlate messages with business context
2664. **Error Handling** - Check `isSuccessful()` for each recipient individually
2675. **Rate Limiting** - Implement retry with backoff for 429 responses
2686. **Bulk Sending** - Use batch send for multiple recipients (more efficient)
269 
270## Trigger Phrases
271 
272- "send SMS Java", "text message Java"
273- "SMS notification", "OTP SMS", "bulk SMS"
274- "delivery report SMS", "Azure Communication Services SMS"
275