Comment recevoir des rapports de livraison SMPP via l'API SMPP

Le protocole Short Message Peer-to-Peer (SMPP) est un pilier de la communication SMS moderne, permettant aux Entités de Messages Courts Externes (ESME) d'échanger des messages et des rapports de livraison avec les Centres de Service de Messages Courts (SMSC). Pour les développeurs utilisant l'API SMPP avec Ozeki SMS Gateway, comprendre comment recevoir des rapports de livraison est essentiel pour suivre le statut des SMS envoyés. Cet article fournit un guide complet sur la réception des rapports de livraison SMPP au niveau du protocole, en se concentrant sur les Unités de Données de Protocole (PDU) SMPP nécessaires pour la configuration de la connexion, sa maintenance et la réception des rapports de livraison, en utilisant Ozeki SMS Gateway comme plateforme principale de serveur API SMPP.

Introduction aux rapports de livraison SMPP et Ozeki SMS Gateway

Les rapports de livraison SMPP sont des notifications envoyées par le SMSC pour informer l'ESME du statut d'un SMS précédemment envoyé, comme s'il a été livré, a échoué ou a été rejeté. Ces rapports sont essentiels pour les applications nécessitant une confirmation de livraison, comme les notifications transactionnelles ou les campagnes marketing. Ozeki SMS Gateway, un logiciel SMPP robuste prenant en charge les versions 3.3, 3.4 et 5.0, simplifie le processus de gestion des rapports de livraison SMPP grâce à son interface intuitive et ses options de configuration puissantes. Cet article détaille les PDU SMPP impliquées dans la configuration d'une connexion client API SMPP, sa maintenance et la réception des rapports de livraison, avec des conseils pratiques pour les utilisateurs d'Ozeki SMS Gateway.

Comprendre les PDU SMPP pour les rapports de livraison

Le protocole SMPP repose sur les Unités de Données de Protocole (PDU) pour gérer la communication entre le client SMPP (par exemple, Ozeki SMS Gateway) et le SMSC. Pour recevoir des rapports de livraison, le client doit établir une connexion, la maintenir et traiter les rapports de livraison entrants. Les PDU clés impliquées sont :

  • bind_transceiver : Établit une connexion pour envoyer et recevoir des SMS et des rapports de livraison.
  • enquire_link : Maintient la connexion pour assurer la réception continue des rapports de livraison.
  • deliver_sm : Livre les rapports de livraison (et les messages SMS) entrants du SMSC au client.
  • unbind : Termine la session SMPP.

Ci-dessous, nous explorons chaque PDU, leur structure et leur rôle dans la réception des rapports de livraison SMPP en utilisant l'API SMPP avec Ozeki SMS Gateway.

Configuration d'une connexion client API SMPP

La réception des rapports de livraison SMPP nécessite une connexion client API SMPP stable vers le SMSC. Ozeki SMS Gateway simplifie ce processus, mais comprendre les opérations au niveau du protocole est essentiel pour les utilisateurs avancés et le dépannage.

1. Configuration du client SMPP dans Ozeki SMS Gateway

Pour configurer une connexion client API SMPP dans Ozeki SMS Gateway pour recevoir des rapports de livraison, suivez ces étapes :

  1. Accéder à la console de gestion : Connectez-vous à l'interface web d'Ozeki SMS Gateway en utilisant le compte administrateur (nom d'utilisateur par défaut : "admin").
  2. Créer une nouvelle connexion : Dans le panneau "Connections", cliquez sur "Add new connection" et sélectionnez "SMPP client" dans la section "IP SMS Connections".
  3. Entrer les paramètres SMPP : Fournissez les détails suivants, généralement fournis par votre fournisseur de services SMS :
    • Nom d'hôte : L'adresse IP ou le nom d'hôte du SMSC (par exemple, "192.168.1.1").
    • Numéro de port : Le port TCP/IP pour la communication SMPP (par défaut 9500, à confirmer avec votre fournisseur).
    • Nom d'utilisateur (System ID) : Votre identifiant de compte SMSC (par exemple, "smppuser").
    • Mot de passe : Le mot de passe pour le System ID (par exemple, "password123").
    • Version SMPP : Sélectionnez v3.4 pour le support transceiver, optimal pour l'envoi et la réception.
    • Type de système : Optionnel, souvent "SMPP", comme spécifié par le fournisseur.
    • Adresse de l'expéditeur : Le numéro de téléphone par défaut pour les SMS sortants (par exemple, "+1234567890").
    • Plage d'adresses : Optionnel, utilisé pour recevoir des messages ou des rapports pour des numéros spécifiques.
  4. Mode de liaison : Sélectionnez "Transceiver" pour activer à la fois l'envoi de SMS et la réception de rapports de livraison sur une seule connexion.
  5. Activer les rapports de livraison : Dans l'onglet "Advanced", cochez "Request delivery report" pour s'assurer que le SMSC envoie des rapports de livraison pour les messages envoyés.
  6. Paramètres de maintien de la connexion : Activez "Send keepalive packets" pour maintenir la connexion et assurer la réception continue des rapports.
  7. Activer la journalisation : Dans l'onglet "Advanced", activez "Log Communication Events" pour capturer les PDU SMPP pour le débogage.
  8. Enregistrer et se connecter : Cliquez sur "OK" pour enregistrer, puis sur "Connect" pour initier la connexion API SMPP.

Ces paramètres préparent Ozeki SMS Gateway à établir une connexion API SMPP en utilisant la PDU bind_transceiver, permettant la réception des rapports de livraison.

2. La PDU bind_transceiver

La PDU bind_transceiver authentifie le client SMPP auprès du SMSC et établit une connexion pour à la fois envoyer des SMS et recevoir des rapports de livraison. C'est la première étape pour activer la fonctionnalité API SMPP.

Structure de la PDU bind_transceiver

Longueur de commande : 4 octets (longueur totale de la PDU)
ID de commande : 0x00000009 (bind_transceiver)
Statut de commande : 0x00000000 (défini à 0 pour les requêtes)
Numéro de séquence : Identifiant unique pour la PDU
System ID : Nom d'utilisateur pour l'authentification (par exemple, "smppuser")
Mot de passe : Mot de passe pour l'authentification (par exemple, "password123")
Type de système : Optionnel, souvent "SMPP"
Version de l'interface : Version SMPP (par exemple, 0x34 pour v3.4)
Plage d'adresses : Optionnel, pour recevoir des messages ou des rapports

Exemple de PDU bind_transceiver (hexadécimal) :

0000002F 00000009 00000000 00000001 736D70707573657200 70617373776F726431323300 534D505000 34 00

Explication :

  • Longueur de commande (0000002F) : Longueur totale de la PDU (47 octets).
  • ID de commande (00000009) : Identifie la PDU comme bind_transceiver.
  • Statut de commande (00000000) : Défini à 0 pour la requête.
  • Numéro de séquence (00000001) : Un ID unique pour suivre la PDU.
  • System ID (736D70707573657200) : ASCII pour "smppuser" avec un terminateur nul.
  • Mot de passe (70617373776F726431323300) : ASCII pour "password123" avec un terminateur nul.
  • Type de système (534D505000) : ASCII pour "SMPP" avec un terminateur nul.
  • Version de l'interface (34) : Indique SMPP v3.4.
  • Plage d'adresses (00) : Nul, car optionnel.

Le SMSC répond avec une PDU bind_transceiver_resp. Un statut de commande de 0x00000000 indique une connexion réussie. Ozeki SMS Gateway enregistre cette interaction dans le journal "Communication Events", utile pour vérifier la connexion.

Maintenance de la connexion API SMPP

Une connexion stable est cruciale pour recevoir des rapports de livraison SMPP, car des interruptions peuvent entraîner des mises à jour de statut manquées. La PDU enquire_link est utilisée pour maintenir la connexion active.

La PDU enquire_link

La PDU enquire_link est envoyée périodiquement par le client SMPP pour confirmer le statut de la connexion, évitant une déconnexion due à l'inactivité.

Structure de la PDU enquire_link

Longueur de commande : 0x00000010 (16 octets)
ID de commande : 0x00000015 (enquire_link)
Statut de commande : 0x00000000 (défini à 0 pour les requêtes)
Numéro de séquence : Identifiant unique pour la PDU

Exemple de PDU enquire_link (hexadécimal) :

00000010 00000015 00000000 00000002

Explication :

  • Longueur de commande (00000010) : Longueur totale (16 octets).
  • ID de commande (00000015) : Identifie la PDU comme enquire_link.
  • Statut de commande (00000000) : Défini à 0 pour la requête.
  • Numéro de séquence (00000002) : Un ID unique pour suivre la PDU.

Le SMSC répond avec une PDU enquire_link_resp pour confirmer le statut de la connexion. Dans Ozeki SMS Gateway, activer "Send keepalive packets" dans l'onglet "Communication" garantit que les PDU enquire_link sont envoyées automatiquement (par exemple, toutes les 30 secondes). Ceci est essentiel pour maintenir une connexion API SMPP fiable pour la réception des rapports de livraison.

Réception des rapports de livraison SMPP

Les rapports de livraison SMPP sont reçus via la PDU deliver_sm, que le SMSC envoie au client pour signaler le statut d'un SMS précédemment envoyé. La PDU contient des détails tels que l'ID du message, le statut de livraison et l'horodatage.

La PDU deliver_sm pour les rapports de livraison

La PDU deliver_sm est utilisée à la fois pour les messages SMS entrants et les rapports de livraison. Pour les rapports de livraison, le champ ESM Class de la PDU est défini pour indiquer un reçu de livraison (généralement 0x04), et le contenu du message inclut un rapport structuré avec des informations de statut.

Structure de la PDU deliver_sm (Rapport de livraison)

Longueur de commande : Variable (dépend de la longueur du rapport)
ID de commande : 0x00000005 (deliver_sm)
Statut de commande : 0x00000000 (défini à 0 pour les requêtes)
Numéro de séquence : Identifiant unique pour la PDU
Type de service : Optionnel, souvent nul
TON de l'adresse source : Type de numéro pour l'expéditeur (SMSC ou destinataire)
NPI de l'adresse source : Indicateur de plan de numérotation pour l'expéditeur
Adresse source : Numéro de téléphone de l'expéditeur ou identifiant SMSC
TON de l'adresse de destination : Type de numéro pour le destinataire (ESME)
NPI de l'adresse de destination : Indicateur de plan de numérotation pour le destinataire
Adresse de destination : Numéro de téléphone du destinataire (par exemple, numéro virtuel de l'ESME)
Classe ESM : 0x04 (indique un reçu de livraison)
Codage des données : Encodage des caractères (par exemple, 0x00 pour GSM 7 bits)
Message court : Texte du rapport de livraison (par exemple, "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000")
Paramètres optionnels : Champs TLV comme receipted_message_id et message_state

Exemple de PDU deliver_sm (hexadécimal) :

0000007A 00000005 00000000 00000003 00 01 01 2B3938373635343332313000 01 01 2B3132333435363738393000 04 00 00 00 00 69643A3132333435207375623A30303120646C7672643A303031207375626D697420646174653A3235303532373034313520646F6E6520646174653A3235303532373034313620737461743A44454C49565244206572723A303030

Explication :

  • Longueur de commande (0000007A) : Longueur totale (122 octets).
  • ID de commande (00000005) : Identifie la PDU comme deliver_sm.
  • Statut de commande (00000000) : Défini à 0 pour la requête.
  • Numéro de séquence (00000003) : Un ID unique pour suivre la PDU.
  • Type de service (00) : Nul, car optionnel.
  • TON de l'adresse source (01) : Numéro international.
  • NPI de l'adresse source (01) : Plan de numérotation ISDN/téléphonique.
  • Adresse source (2B3938373635343332313000) : ASCII pour "+9876543210" (numéro du destinataire).
  • TON de l'adresse de destination (01) : Numéro international.
  • NPI de l'adresse de destination (01) : Plan de numérotation ISDN/téléphonique.
  • Adresse de destination (2B3132333435363738393000) : ASCII pour "+1234567890" (numéro de l'ESME).
  • Classe ESM (04) : Indique un reçu de livraison.
  • Codage des données (00) : Encodage GSM 7 bits.
  • Message court : ASCII pour "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000".

Champs du rapport de livraison :

  • id : ID du message attribué par le SMSC (par exemple, "12345").
  • sub : Nombre de destinataires (par exemple, "001").
  • dlvrd : Nombre de messages livrés (par exemple, "001").
  • submit date : Horodatage de soumission (par exemple, "2505270415" pour le 27 mai 2025 à 04:15).
  • done date : Horodatage de livraison (par exemple, "2505270416").
  • stat : Statut de livraison (par exemple, "DELIVRD" pour livré, "UNDELIV" pour non livrable).
  • err : Code d'erreur (par exemple, "000" pour aucune erreur).

Le client doit répondre avec une PDU deliver_sm_resp pour accuser réception. Ozeki SMS Gateway gère cela automatiquement et route le rapport de livraison vers l'application ou la base de données configurée, en l'enregistrant dans le panneau "Messages".

Configuration d'Ozeki SMS Gateway pour la réception des rapports de livraison

Pour s'assurer qu'Ozeki SMS Gateway traite correctement les rapports de livraison SMPP :

  1. Activer les rapports de livraison : Dans la configuration du client SMPP, cochez "Request delivery report" dans l'onglet "Advanced" pour demander au SMSC d'envoyer des rapports de livraison.
  2. Configuration du numéro virtuel : Assurez-vous que le SMSC est configuré pour envoyer les rapports de livraison au numéro virtuel ou à la plage d'adresses spécifiée dans les paramètres du client SMPP.
  3. Intégration de base de données : Configurez Ozeki pour stocker les rapports de livraison dans une base de données en modifiant l'instruction SQL SELECT dans la configuration "Database user" (par exemple, "SELECT id, sender, receiver, msg, msgtype, status FROM ozekimessagein WHERE msgtype='DLR'").
  4. Journalisation : Activez la journalisation des PDU SMPP pour surveiller les PDU deliver_sm entrantes pour le débogage.

Avec ces paramètres, Ozeki SMS Gateway traitera et stockera les rapports de livraison, les rendant accessibles pour les applications ou une analyse ultérieure.

Terminaison de la connexion API SMPP

Lorsque la session API SMPP n'est plus nécessaire, le client envoie une PDU unbind pour terminer la connexion de manière gracieuse.

La PDU unbind

La PDU unbind signale au SMSC de fermer la session SMPP.

Structure de la PDU unbind

Longueur de commande : 0x00000010 (16 octets)
ID de commande : 0x00000006 (unbind)
Statut de commande : 0x00000000 (défini à 0 pour les requêtes)
Numéro de séquence : Identifiant unique pour la PDU

Exemple de PDU unbind (hexadécimal) :

00000010 00000006 00000000 00000004

Explication :

  • Longueur de commande (00000010) : Longueur totale (16 octets).
  • ID de commande (00000006) : Identifie la PDU comme unbind.
  • Statut de commande (00000000) : Défini à 0 pour la requête.
  • Numéro de séquence (00000004) : Un ID unique pour suivre la PDU.

Le SMSC répond avec une PDU unbind_resp, confirmant la fin de la session. Dans Ozeki SMS Gateway, cela peut être initié en cliquant sur "Disconnect" dans le panneau "Connections".

Bonnes pratiques pour la gestion des rapports de livraison API SMPP

Pour optimiser votre implémentation API SMPP pour la réception des rapports de livraison avec Ozeki SMS Gateway :

  • Demander des rapports de livraison : Activez toujours l'option "Request delivery report" lors de l'envoi de SMS pour garantir que le SMSC génère des rapports.
  • Surveiller les journaux : Utilisez les journaux des PDU SMPP pour dépanner les problèmes avec les PDU deliver_sm, en particulier pour les rapports de livraison.
  • Utiliser le mode transceiver : Préférez le mode transceiver pour l'efficacité, car il supporte à la fois l'envoi de SMS et la réception de rapports de livraison.
  • Sécuriser les connexions : Utilisez SMPPS (SMPP over SSL/TLS) si supporté par votre fournisseur pour garantir une transmission sécurisée des rapports de livraison.
  • Analyser les rapports de livraison : Configurez les applications pour analyser le champ "Short Message" de la PDU deliver_sm pour extraire les informations de statut (par exemple, "DELIVRD" ou "UNDELIV") pour des insights actionnables.

Conclusion

La réception des rapports de livraison SMPP en utilisant l'API SMPP avec Ozeki SMS Gateway implique l'établissement d'une connexion avec la PDU bind_transceiver, sa maintenance avec les PDU enquire_link et le traitement des rapports de livraison via la PDU deliver_sm. En configurant correctement Ozeki SMS Gateway et en comprenant le protocole SMPP sous-jacent, les développeurs peuvent construire des systèmes fiables pour suivre le statut de livraison des SMS. La robustesse de l'API SMPP et la configuration flexible d'Ozeki en font un excellent choix pour la gestion des rapports de livraison dans les applications SMS à haut volume. Pour plus de détails, consultez la documentation d'Ozeki SMS Gateway ou contactez votre fournisseur de services SMS pour des exigences de configuration spécifiques.

More information