Interface SMPP

Informations sur l'interface

Ce protocole définit le protocole de communication SMPP du service EngageLab OTP, conçu pour assurer un envoi de messages et un rapport de statut efficaces et fiables via des connexions TCP. Les informations de l'interface comprennent l'adresse IP, le numéro de port ainsi que les informations d'authentification requises pour la connexion. Veuillez vous assurer d'effectuer une configuration correcte conformément au compte et au mot de passe fournis par le canal autorisé.

Adresse SMPP

Adresse SMPP : otpsmpp.api.engagelab.cc Veuillez obtenir les informations suivantes auprès d'un canal autorisé (par exemple le service commercial ou le support technique) :

• Port : { port }
• Compte : { system_id }
• Mot de passe : { password }

Établir la connexion

Paquet client

Une fois la connexion TCP établie, le premier paquet doit envoyer la commande BindTransceiver (soit 0x00000009) pour effectuer la vérification d'authentification. Ce paquet doit contenir les champs suivants :

• system_id : le compte système attribué au client, utilisé pour identifier son identité.
• password : le mot de passe d'accès correspondant au compte système, utilisé pour l'authentification de l'identité.

Réponse du serveur

Réponse de succès

• Le serveur envoie une réponse avec la commande BindTransceiverResp (soit 0x80000009).
• Le champ system_id est renseigné avec une valeur identique au champ system_id reçu.

Réponse d'échec

• Si l'authentification échoue, le serveur ferme cette connexion TCP et enregistre la raison de l'échec.

Envoi de messages

Logique côté serveur

L'envoi de messages utilise la commande SUBMIT_SM (soit 0x00000004) pour soumettre les demandes d'envoi de messages. La logique côté serveur est la suivante :

1. Le serveur analyse le contenu de la requête et utilise systématiquement le canal SMS pour l'envoi.
2. L'envoi du message se fait en mode synchrone, le résultat étant renvoyé avec la commande SUBMIT_SM_RESP (soit 0x80000004).
3. Le statut de livraison est rapporté via des messages, voir Rapport de livraison pour plus de détails.
4. Il est recommandé d'utiliser l'encodage UCS2 pour prendre en charge les caractères spéciaux et l'internationalisation.

Paquet client

Le client envoie la commande SUBMIT_SM (soit 0x00000004) pour soumettre un message, qui doit contenir les champs suivants :

1. service_type
   • Valeurs : MSG / CODE / MRKT
   • Valeur par défaut : MSG
2. source_addr
   • Peut être laissé vide, actuellement non utilisé dans OTP.
3. destination_addr
   • Destinataire du message, doit être au format de numéro de mobile international (par ex. +6598765432).
4. short_message
   • Contenu du message, au format JSON, comme suit :
     { "id": "xxx", // ID du modèle "language": "default", // Langue utilisée, par défaut « default » "code": "xx", // Code de vérification, utilisé uniquement lorsque service_type vaut code "params": { // Paires clé-valeur personnalisées "key1": "val1" // val au format chaîne de caractères } }

                   
                   {
       "id": "xxx",          // ID du modèle
       "language": "default", // Langue utilisée, par défaut « default »
       "code": "xx",          // Code de vérification, utilisé uniquement lorsque service_type vaut code
       "params": {            // Paires clé-valeur personnalisées
         "key1": "val1"       // val au format chaîne de caractères
       }
     }
     
                 

     Afficher ce bloc de code dans la fenêtre flottante
5. data_coding
   • Il est recommandé d'utiliser l'encodage UCS2 pour garantir l'analyse correcte des caractères spéciaux {}.
   • Si l'envoi direct de {} est pris en charge, l'encodage par défaut (soit 0x00) peut être utilisé.
6. status dans le header
   • À définir sur 0x00000000.

Réponse du serveur

Le serveur envoie la commande SUBMIT_SM_RESP (soit 0x80000004) pour répondre au résultat de l'envoi du message.

Réponse de succès

• Valeur du champ status dans le header : 0x00000000
• Champ MESSAGE_ID : ID du message de réponse, utilisé pour associer le rapport de livraison.

Réponse d'échec

• Le serveur renseigne le champ status dans le header pour indiquer la raison de l'échec :

Rapport de livraison

Le serveur rapporte le rapport de livraison via la commande DELIVER_SM (soit 0x00000005). Les champs spécifiques sont les suivants :

1. service_type
   • Valeur fixe : MSG
2. source_addr
   • Laissé vide.
3. destination_addr
   • Identique au destination_addr de la commande SUBMIT_SM.
4. data_coding
   • Méthode d'encodage : valeur par défaut 0x00.
5. esm_class
   • À définir sur 0x00.
6. short_message
   • Le rapport de livraison est encapsulé au format delivery receipt.
7. ReceiptedMessageID dans tlv
   • ID du message, utilisé pour l'identification par association.
8. MessageState dans tlv
   • Statut du message, valeur du champ 0x0427.

Analyse du statut

Dans le champ short_message, la signification de la valeur stat est la suivante :

Autres précisions

Commandes invalides

Pour les commandes invalides soumises par le client, le serveur renvoie la commande GENERIC_NACK (soit 0x80000000) et enregistre les journaux correspondants. Le serveur ne prend en charge que les commandes suivantes :

1. Commande EnquireLink (soit 0x00000015)
2. Commande Unbind (soit 0x00000006)
3. Commande SubmitSM (soit 0x00000004)
4. Commande DeliverSMResp (soit 0x80000005)
5. Commande BindTransceiver (soit 0x00000009)

Maintien de l'activité

Le client doit envoyer une commande EnquireLink (soit 0x00000015) toutes les 30 secondes (tolérance ±5 secondes) afin de garantir que la connexion reste active.

Signification des statuts d'envoi

Glossaire

• SMPP : Short Message Peer-to-Peer Protocol (protocole pair à pair de messages courts), utilisé pour l'échange de messages au sein des passerelles SMS.
• SUBMIT_SM : commande SMPP servant à soumettre des messages SMS.
• DELIVER_SM : commande SMPP utilisée par le serveur pour rapporter le statut de livraison des messages.

Pour toute question, veuillez contacter le support technique OTP.