API SMPP

Informations sur l’API

Ce document définit le protocole de communication SMPP pour le service OTP d’EngageLab. Il est conçu pour permettre une livraison des messages et un reporting de statut efficaces et fiables sur des connexions TCP. Les informations de l’API incluent l’adresse IP, le numéro de port et les informations d’authentification requises pour la connexion. Veuillez vous assurer que le compte et le mot de passe fournis via les canaux autorisés sont correctement configurés.

Adresse SMPP

Adresse SMPP : otpsmpp.api.engagelab.cc

Veuillez obtenir les informations suivantes via un canal autorisé, tel que le support commercial ou technique :

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

Établissement d’une connexion

Paquet client

Après avoir établi la connexion TCP, le premier paquet doit envoyer la commande BindTransceiver (0x00000009) pour l’authentification. Ce paquet doit inclure les champs suivants :

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

Réponse du serveur

Réponse réussie

• Le serveur renvoie la commande BindTransceiverResp (0x80000009).
• Le champ system_id est renseigné avec la même valeur que le champ system_id reçu.

Échec de la réponse

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

Envoi de message

Logique du serveur

L’envoi de message utilise la commande SUBMIT_SM (0x00000004) pour soumettre une demande de livraison de message. La logique du serveur est la suivante :

1. Le serveur analyse le contenu de la requête et utilise toujours le canal SMS pour la livraison.
2. La livraison du message est synchrone et le résultat est renvoyé via la commande SUBMIT_SM_RESP (0x80000004).
3. Le statut de livraison est signalé via des rapports de livraison. Pour plus de détails, voir Rapports de livraison.
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 (0x00000004) pour soumettre un message. Le paquet doit inclure les champs suivants :

1. service_type

   • Valeur : MSG / CODE / MRKT
   • Valeur par défaut : MSG

2. source_addr

   • Peut être laissé vide et n’est actuellement pas utilisé dans OTP.

3. destination_addr

   • Destination du message, qui doit être au format international de numéro de mobile (par exemple, +6598765432).

4. short_message

   • Le contenu du message utilise le format JSON, comme indiqué ci-dessous :
     { "id": "xxx", // ID du modèle "language": "default", // Langue utilisée ; la valeur par défaut est default "code": "xx", // Code de vérification ; utilisé uniquement lorsque service_type est CODE "params": { // Paires clé-valeur personnalisées "key1": "val1" // val doit être au format chaîne de caractères } }

                   
                   {
       "id": "xxx",           // ID du modèle
       "language": "default", // Langue utilisée ; la valeur par défaut est default
       "code": "xx",          // Code de vérification ; utilisé uniquement lorsque service_type est CODE
       "params": {            // Paires clé-valeur personnalisées
         "key1": "val1"       // val doit être 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 que les caractères spéciaux tels que {} sont correctement analysés.
   • Si la transmission directe de {} est prise en charge, l’encodage par défaut peut être utilisé (0x00).

6. status in the header

   • Définir sur 0x00000000.

Réponse du serveur

Le serveur envoie la commande SUBMIT_SM_RESP (0x80000004) en réponse au résultat de livraison du message.

Réponse réussie

• Valeur du champ status dans l’en-tête : 0x00000000
• Champ MESSAGE_ID : ID du message de réponse, utilisé pour faire la corrélation avec les rapports de livraison.

Échec de la réponse

• Le serveur renseigne le champ status dans l’en-tête pour indiquer la raison de l’échec :

Rapports de livraison

Le serveur signale le statut de livraison via la commande DELIVER_SM (0x00000005). Les champs concernés sont les suivants :

1. service_type

   • Valeur fixe : MSG

2. source_addr

   • Laisser 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 in TLV

   • ID du message, utilisé pour la corrélation et l’identification.

8. MessageState in TLV

   • Statut du message, valeur du champ 0x0427.

Analyse du statut

Dans le champ short_message, la signification des valeurs stat est la suivante :

Autres remarques

Commandes invalides

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

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

Keepalive

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

Signification du statut d’envoi

Terminologie

• SMPP : Short Message Peer-to-Peer Protocol, utilisé pour l’échange de messages avec les passerelles SMS.
• SUBMIT_SM : commande SMPP permettant de soumettre des messages SMS.
• DELIVER_SM : commande SMPP utilisée par le serveur pour signaler le statut de livraison des messages.

Si vous avez des questions, veuillez contacter le support technique OTP.