Comment envoyer des SMS via l'API SMPP en utilisant Java

L'API Short Message Peer-to-Peer (SMPP) est un protocole de télécommunications puissant conçu pour échanger des messages SMS entre les centres de service de messages courts (SMSC) et les entités externes de messagerie courte (ESME). En utilisant Java et l'API SMPP, les développeurs peuvent construire des applications robustes pour envoyer et recevoir des SMS efficacement. Ce guide complet vous explique comment implémenter l'API SMPP en Java pour vous connecter à la passerelle SMS Ozeki, avec des exemples de code pratiques pour la gestion des connexions, l'envoi de messages et le traitement des rapports de livraison.

Pourquoi utiliser Java et l'API SMPP pour la messagerie SMS ?

Java est un langage de programmation polyvalent et indépendant de la plateforme, largement utilisé pour développer des applications d'entreprise. Associé à l'API SMPP, Java permet aux développeurs de créer des solutions SMS évolutives qui s'intègrent parfaitement aux passerelles SMS comme Ozeki. Le protocole SMPP est idéal pour les applications SMS à haut débit grâce à sa fiabilité, sa prise en charge des envois en masse et ses capacités de suivi de livraison. Ce guide utilise la bibliothèque jSMPP, une implémentation pure Java du protocole SMPP, pour simplifier le développement.

Configuration du client API SMPP Java pour l'envoi de SMS

Pour commencer à envoyer des SMS avec l'API SMPP en Java, vous devez créer un compte utilisateur SMPP sur le serveur SMPP de la passerelle SMS Ozeki et configurer votre application Java pour se connecter à son serveur SMPP. La bibliothèque jSMPP est un choix populaire pour les développeurs Java grâce à sa prise en charge complète des fonctionnalités du protocole SMPP. Ci-dessous, nous détaillons les étapes pour configurer votre projet Java.

Étape 1 : Ajouter la dépendance jSMPP

Pour utiliser la bibliothèque jSMPP dans votre projet Java, ajoutez la dépendance Maven suivante dans votre fichier pom.xml : 

<dependency>
    <groupId>org.jsmpp</groupId>
    <artifactId>jsmpp</artifactId>
    <version>2.3.10</version>
</dependency>

Cette dépendance fournit toutes les classes nécessaires pour implémenter l'API SMPP en Java, y compris la gestion des sessions, l'encodage des messages et le traitement des accusés de réception.

Étape 2 : Exemple de connexion SMPP de base

La connexion à un serveur SMPP nécessite l'établissement d'une session et sa liaison à la passerelle SMS Ozeki. Le code Java suivant montre comment créer un client SMPP simple en utilisant la bibliothèque jSMPP : 

import org.jsmpp.*;
import org.jsmpp.bean.*;
import org.jsmpp.session.*;

public class SimpleSMPPClient {
    public static void main(String[] args) {
        SMPPSession session = new SMPPSession();
        try {
            // Connexion et liaison à la passerelle SMS Ozeki
            session.connectAndBind(
                "votre.serveur.ozeki", 
                2775, 
                new BindParameter(
                    BindType.BIND_TX, 
                    "votre_nom_utilisateur", 
                    "votre_mot_de_passe", 
                    "cp", 
                    TypeOfNumber.ALPHANUMERIC, 
                    NumberingPlanIndicator.UNKNOWN, 
                    null)
            );
            
            System.out.println("Connexion au serveur SMPP réussie");
            
            // Ajouter le code d'envoi de message ici
            
        } catch (Exception e) {
            System.err.println("Échec de la connexion et de la liaison au serveur SMPP : " + e.getMessage());
        } finally {
            session.unbindAndClose();
        }
    }
}

Dans cet exemple, remplacez votre.serveur.ozeki, votre_nom_utilisateur, et votre_mot_de_passe par les identifiants fournis par votre administrateur de la passerelle SMS Ozeki. Le BindType.BIND_TX indique une liaison en mode émetteur, adaptée pour l'envoi de SMS.

Gestion des connexions API SMPP en Java pour une livraison fiable des SMS

Une livraison fiable des SMS nécessite le maintien d'une connexion SMPP active. Le protocole SMPP utilise des messages de maintien de liaison (PDU enquire_link) pour garantir que la connexion reste active. Voici un exemple de configuration des paramètres de maintien de liaison et de surveillance des changements d'état de session en Java : 

session.setEnquireLinkTimer(30000); // Envoi d'un maintien de liaison toutes les 30 secondes
session.setTransactionTimer(10000); // Définition du délai d'expiration des transactions à 10 secondes

// Ajout d'un écouteur d'état de session pour la surveillance
session.addSessionStateListener(new SessionStateListener() {
    @Override
    public void onStateChange(SessionState newState, SessionState oldState, Session source) {
        System.out.println("L'état de la session SMPP est passé de " + oldState + " à " + newState);
    }
});

Ces paramètres garantissent la stabilité de la connexion, et l'écouteur d'état de session vous aide à surveiller les changements, comme les déconnexions, pour une gestion robuste des erreurs.

Envoi de SMS avec Java via l'API SMPP

Une fois connecté, vous pouvez envoyer des SMS en utilisant la PDU submit_sm. La méthode Java suivante montre comment envoyer un SMS avec l'API SMPP en Java : 

public static void sendSMS(SMPPSession session, String sender, String recipient, String message) throws Exception {
    try {
        String messageId = session.submitShortMessage(
            "CMT", // Type de service
            TypeOfNumber.ALPHANUMERIC, // TON source
            NumberingPlanIndicator.UNKNOWN, // NPI source
            sender, // Adresse de l'expéditeur
            TypeOfNumber.INTERNATIONAL, // TON destination
            NumberingPlanIndicator.ISDN, // NPI destination
            recipient, // Adresse du destinataire
            new ESMClass(), // Classe ESM
            (byte)0, // ID du protocole
            (byte)1, // Drapeau de priorité
            null, // Heure de livraison planifiée
            null, // Période de validité
            new RegisteredDelivery(SMSCDeliveryReceipt.SUCCESS_FAILURE), // Accusé de réception
            (byte)0, // Drapeau de remplacement
            new GeneralDataCoding(Alphabet.ALPHA_DEFAULT), // Codage des données
            (byte)0, // ID de message par défaut
            message.getBytes() // Contenu du message
        );
        
        System.out.println("SMS envoyé avec l'ID de message : " + messageId);
    } catch (PDUException e) {
        System.err.println("Paramètre PDU invalide : " + e.getMessage());
        throw e;
    } catch (ResponseTimeoutException e) {
        System.err.println("Délai de réponse dépassé : " + e.getMessage());
        throw e;
    } catch (InvalidResponseException e) {
        System.err.println("Réponse invalide : " + e.getMessage());
        throw e;
    } catch (NegativeResponseException e) {
        System.err.println("Réponse négative reçue : " + e.getMessage());
        throw e;
    } catch (Exception e) {
        System.err.println("Échec de l'envoi du SMS : " + e.getMessage());
        throw e;
    }
}

Cette méthode envoie un SMS avec suivi des accusés de réception. Le paramètre RegisteredDelivery garantit que vous recevez des notifications sur l'état de livraison du message.

Traitement des rapports de livraison SMS avec Java et l'API SMPP

Pour suivre si un SMS a été livré avec succès, vous pouvez lier votre session SMPP en mode transceiver (BindType.BIND_TRX) et implémenter un écouteur de réception de messages. Voici un exemple de traitement des rapports de livraison en Java : 

// Liaison en mode transceiver pour envoyer et recevoir des messages
BindParameter bindParam = new BindParameter(
    BindType.BIND_TRX,
    "votre_nom_utilisateur",
    "votre_mot_de_passe",
    "cp",
    TypeOfNumber.ALPHANUMERIC,
    NumberingPlanIndicator.UNKNOWN,
    null
);

// Configuration de l'écouteur de réception pour les rapports de livraison
session.setMessageReceiverListener(new MessageReceiverListener() {
    @Override
    public void onAcceptDeliverSm(DeliverSm deliverSm) {
        if (MessageType.SMSC_DEL_RECEIPT.containedIn(deliverSm.getEsmClass())) {
            DeliveryReceipt delReceipt = deliverSm.getShortMessageAsDeliveryReceipt();
            System.out.println(String.format(
                "Reçu un rapport de livraison pour le message %s : %s",
                delReceipt.getId(),
                delReceipt.getFinalStatus()
            ));
        }
        
        // Réponse au rapport de livraison
        try {
            byte[] messageId = new byte[]{1};
            session.deliverSmResponse(0, messageId, deliverSm);
        } catch (PDUException e) {
            System.err.println("Échec de la réponse à deliver_sm : " + e.getMessage());
        }
    }
});

Ce code traite les accusés de réception, vous permettant de suivre le succès ou l'échec de chaque SMS envoyé via l'API SMPP en Java.

Client SMPP Java complet pour l'envoi de SMS via l'API SMPP

Voici une classe Java complète qui intègre la gestion des connexions, l'envoi de messages et le traitement des rapports de livraison. Cette implémentation est prête pour la production avec une gestion appropriée des erreurs et des ressources : 

import org.jsmpp.*;
import org.jsmpp.bean.*;
import org.jsmpp.session.*;
import org.jsmpp.util.*;

public class SMPPClient implements AutoCloseable {
    private SMPPSession session;
    private String host;
    private int port;
    private String username;
    private String password;
    
    public SMPPClient(String host, int port, String username, String password) {
        this.host = host;
        this.port = port;
        this.username = username;
        this.password = password;
        this.session = new SMPPSession();
    }
    
    public void connect() throws Exception {
        try {
            BindParameter bindParam = new BindParameter(
                BindType.BIND_TRX,
                username,
                password,
                "cp",
                TypeOfNumber.ALPHANUMERIC,
                NumberingPlanIndicator.UNKNOWN,
                null
            );
            
            session.connectAndBind(host, port, bindParam);
            
            // Configuration des paramètres de session
            session.setEnquireLinkTimer(30000);
            session.setTransactionTimer(10000);
            
            // Configuration du gestionnaire d'accusés de réception
            session.setMessageReceiverListener(new DeliveryReceiptListener());
            
            System.out.println("Connexion au serveur SMPP réussie");
        } catch (Exception e) {
            System.err.println("Échec de la connexion au serveur SMPP : " + e.getMessage());
            throw e;
        }
    }
    
    public String sendSMS(String sender, String recipient, String message) throws Exception {
        try {
            return session.submitShortMessage(
                "CMT",
                TypeOfNumber.ALPHANUMERIC,
                NumberingPlanIndicator.UNKNOWN,
                sender,
                TypeOfNumber.INTERNATIONAL,
                NumberingPlanIndicator.ISDN,
                recipient,
                new ESMClass(),
                (byte)0,
                (byte)1,
                null,
                null,
                new RegisteredDelivery(SMSCDeliveryReceipt.SUCCESS_FAILURE),
                (byte)0,
                new GeneralDataCoding(Alphabet.ALPHA_DEFAULT),
                (byte)0,
                message.getBytes()
            );
        } catch (Exception e) {
            System.err.println("Échec de l'envoi du SMS : " + e.getMessage());
            throw e;
        }
    }
    
    @Override
    public void close() {
        if (session != null) {
            session.unbindAndClose();
        }
    }
    
    private static class DeliveryReceiptListener implements MessageReceiverListener {
        @Override
        public void onAcceptDeliverSm(DeliverSm deliverSm) {
            if (MessageType.SMSC_DEL_RECEIPT.containedIn(deliverSm.getEsmClass())) {
                DeliveryReceipt delReceipt = deliverSm.getShortMessageAsDeliveryReceipt();
                System.out.println(String.format(
                    "Reçu un rapport de livraison pour le message %s : %s",
                    delReceipt.getId(),
                    delReceipt.getFinalStatus()
                ));
            }
        }
    }
    
    public static void main(String[] args) {
        try (SMPPClient client = new SMPPClient(
                "votre.serveur.ozeki", 
                2775, 
                "votre_nom_utilisateur", 
                "votre_mot_de_passe")) {
            
            client.connect();
            
            String messageId = client.sendSMS(
                "12345", 
                "+1234567890", 
                "Bonjour depuis le client SMPP Java !"
            );
            
            System.out.println("SMS envoyé avec l'ID : " + messageId);
            
            // Maintien de l'application en cours d'exécution pour recevoir les rapports de livraison
            System.out.println("Appuyez sur Ctrl+C pour quitter...");
            Thread.sleep(Long.MAX_VALUE);
            
        } catch (Exception e) {
            System.err.println("Erreur dans le client SMPP : " + e.getMessage());
        }
    }
}

Cette implémentation complète encapsule les fonctionnalités du client SMPP dans une classe réutilisable, facilitant son intégration dans des applications Java plus grandes. L'interface AutoCloseable garantit un nettoyage approprié des ressources.

Bonnes pratiques pour la construction de clients SMPP Java

Pour garantir que votre client API SMPP Java est robuste et évolutif, suivez ces bonnes pratiques :

  • Pool de connexions : Utilisez un pool de connexions pour les applications SMS à haut volume afin de gérer efficacement plusieurs sessions SMPP.
  • Gestion des exceptions : Implémentez une gestion complète des exceptions pour récupérer des problèmes réseau ou des erreurs serveur.
  • Pools de threads : Utilisez des pools de threads pour le traitement concurrent des messages afin d'améliorer les performances.
  • File d'attente des messages : Implémentez un mécanisme de file d'attente pour garantir une livraison fiable des messages lors des perturbations réseau.
  • Surveillance des connexions : Surveillez l'état de la session SMPP et implémentez une logique de reconnexion automatique pour la fiabilité.
  • Encodage des caractères : Gérez différents encodages de caractères (par exemple, GSM 7-bit, UCS-2) pour prendre en charge la messagerie SMS internationale.

Conclusion

L'implémentation de l'API SMPP en Java avec la passerelle SMS Ozeki offre une solution puissante pour envoyer et recevoir des SMS dans vos applications. La bibliothèque jSMPP simplifie les complexités du protocole SMPP, permettant aux développeurs de se concentrer sur la construction de fonctionnalités de messagerie robustes. Ce guide a couvert les bases de la configuration d'un client SMPP Java, de la gestion des connexions, de l'envoi de SMS et du traitement des rapports de livraison. En suivant les exemples et bonnes pratiques fournis, vous pouvez créer des applications SMS évolutives et fiables en utilisant Java et l'API SMPP.

Pour les environnements de production, envisagez d'ajouter des fonctionnalités avancées comme la concaténation des messages pour les SMS longs, des journaux détaillés et une surveillance des performances. Le protocole SMPP offre des capacités supplémentaires, comme la livraison planifiée des messages et les paramètres de priorité, pour améliorer votre application au fur et à mesure que les besoins évoluent.

More information