Azure Communication SMS (Java)

Envoyez des messages SMS à un ou plusieurs destinataires avec rapports de livraison.

Installation

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-sms</artifactId>
    <version>1.2.0</version>
</dependency>

Création du client

import com.azure.communication.sms.SmsClient;
import com.azure.communication.sms.SmsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Avec DefaultAzureCredential (recommandé)
SmsClient smsClient = new SmsClientBuilder()
    .endpoint("https://<resource>.communication.azure.com")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

// Avec chaîne de connexion
SmsClient smsClient = new SmsClientBuilder()
    .connectionString("<connection-string>")
    .buildClient();

// Avec AzureKeyCredential
import com.azure.core.credential.AzureKeyCredential;

SmsClient smsClient = new SmsClientBuilder()
    .endpoint("https://<resource>.communication.azure.com")
    .credential(new AzureKeyCredential("<access-key>"))
    .buildClient();

// Client asynchrone
SmsAsyncClient smsAsyncClient = new SmsClientBuilder()
    .connectionString("<connection-string>")
    .buildAsyncClient();

Envoyer un SMS à un seul destinataire

import com.azure.communication.sms.models.SmsSendResult;

// Envoi simple
SmsSendResult result = smsClient.send(
    "+14255550100",      // De (votre numéro de téléphone ACS)
    "+14255551234",      // À
    "Your verification code is 123456");

System.out.println("Message ID: " + result.getMessageId());
System.out.println("To: " + result.getTo());
System.out.println("Success: " + result.isSuccessful());

if (!result.isSuccessful()) {
    System.out.println("Error: " + result.getErrorMessage());
    System.out.println("Status: " + result.getHttpStatusCode());
}

Envoyer un SMS à plusieurs destinataires

import com.azure.communication.sms.models.SmsSendOptions;
import java.util.Arrays;
import java.util.List;

List<String> recipients = Arrays.asList(
    "+14255551111",
    "+14255552222",
    "+14255553333"
);

// Avec options
SmsSendOptions options = new SmsSendOptions()
    .setDeliveryReportEnabled(true)
    .setTag("marketing-campaign-001");

Iterable<SmsSendResult> results = smsClient.sendWithResponse(
    "+14255550100",      // De
    recipients,          // Liste de destinataires
    "Flash sale! 50% off today only.",
    options,
    Context.NONE
).getValue();

for (SmsSendResult result : results) {
    if (result.isSuccessful()) {
        System.out.println("Sent to " + result.getTo() + ": " + result.getMessageId());
    } else {
        System.out.println("Failed to " + result.getTo() + ": " + result.getErrorMessage());
    }
}

Options d'envoi

SmsSendOptions options = new SmsSendOptions();

// Activer les rapports de livraison (envoyés via Event Grid)
options.setDeliveryReportEnabled(true);

// Ajouter une balise personnalisée pour le suivi
options.setTag("order-confirmation-12345");

Gestion des réponses

import com.azure.core.http.rest.Response;

Response<Iterable<SmsSendResult>> response = smsClient.sendWithResponse(
    "+14255550100",
    Arrays.asList("+14255551234"),
    "Hello!",
    new SmsSendOptions().setDeliveryReportEnabled(true),
    Context.NONE
);

// Vérifier la réponse HTTP
System.out.println("Status code: " + response.getStatusCode());
System.out.println("Headers: " + response.getHeaders());

// Traiter les résultats
for (SmsSendResult result : response.getValue()) {
    System.out.println("Message ID: " + result.getMessageId());
    System.out.println("Successful: " + result.isSuccessful());

    if (!result.isSuccessful()) {
        System.out.println("HTTP Status: " + result.getHttpStatusCode());
        System.out.println("Error: " + result.getErrorMessage());
    }
}

Opérations asynchrones

import reactor.core.publisher.Mono;

SmsAsyncClient asyncClient = new SmsClientBuilder()
    .connectionString("<connection-string>")
    .buildAsyncClient();

// Envoyer un seul message
asyncClient.send("+14255550100", "+14255551234", "Async message!")
    .subscribe(
        result -> System.out.println("Sent: " + result.getMessageId()),
        error -> System.out.println("Error: " + error.getMessage())
    );

// Envoyer à plusieurs avec options
SmsSendOptions options = new SmsSendOptions()
    .setDeliveryReportEnabled(true);

asyncClient.sendWithResponse(
    "+14255550100",
    Arrays.asList("+14255551111", "+14255552222"),
    "Bulk async message",
    options)
    .subscribe(response -> {
        for (SmsSendResult result : response.getValue()) {
            System.out.println("Result: " + result.getTo() + " - " + result.isSuccessful());
        }
    });

Gestion des erreurs

import com.azure.core.exception.HttpResponseException;

try {
    SmsSendResult result = smsClient.send(
        "+14255550100",
        "+14255551234",
        "Test message"
    );

    // Les erreurs de message individuelles ne lèvent pas d'exceptions
    if (!result.isSuccessful()) {
        handleMessageError(result);
    }

} catch (HttpResponseException e) {
    // Échecs au niveau de la requête (authentification, réseau, etc.)
    System.out.println("Request failed: " + e.getMessage());
    System.out.println("Status: " + e.getResponse().getStatusCode());
} catch (RuntimeException e) {
    System.out.println("Unexpected error: " + e.getMessage());
}

private void handleMessageError(SmsSendResult result) {
    int status = result.getHttpStatusCode();
    String error = result.getErrorMessage();

    if (status == 400) {
        System.out.println("Invalid phone number: " + result.getTo());
    } else if (status == 429) {
        System.out.println("Rate limited - retry later");
    } else {
        System.out.println("Error " + status + ": " + error);
    }
}

Rapports de livraison

Les rapports de livraison sont envoyés via Azure Event Grid. Configurez un abonnement Event Grid pour votre ressource ACS.

// Gestionnaire de webhook Event Grid (dans votre point de terminaison)
public void handleDeliveryReport(String eventJson) {
    // Analyser l'événement Event Grid
    // Type d'événement : Microsoft.Communication.SMSDeliveryReportReceived

    // Les données d'événement contiennent :
    // - messageId : correspond à SmsSendResult.getMessageId()
    // - from : numéro de l'expéditeur
    // - to : numéro du destinataire
    // - deliveryStatus : "Delivered", "Failed", etc.
    // - deliveryStatusDetails : statut détaillé
    // - receivedTimestamp : moment où le statut a été reçu
    // - tag : votre balise personnalisée de SmsSendOptions
}

Propriétés de SmsSendResult

Variables d'environnement

AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com
AZURE_COMMUNICATION_CONNECTION_STRING=endpoint=https://...;accesskey=...
SMS_FROM_NUMBER=+14255550100

Bonnes pratiques

1. Format du numéro de téléphone - Utiliser le format E.164 : +[code pays][numéro]
2. Rapports de livraison - Activer pour les messages critiques (OTP, alertes)
3. Balisage - Utiliser des balises pour corréler les messages avec le contexte métier
4. Gestion des erreurs - Vérifier isSuccessful() pour chaque destinataire individuellement
5. Limitation de débit - Implémenter une tentative avec backoff pour les réponses 429
6. Envoi en masse - Utiliser l'envoi par lot pour plusieurs destinataires (plus efficace)

Phrases déclencheurs

• "send SMS Java", "text message Java"
• "SMS notification", "OTP SMS", "bulk SMS"
• "delivery report SMS", "Azure Communication Services SMS"