Envoi du code de vérification

Cette interface permet à la plateforme EngageLab de générer un code de vérification et de l'envoyer selon la stratégie de canal définie dans le modèle.

Si vous préférez générer le code de vérification vous-même plutôt que de le faire générer par la plateforme EngageLab, vous pouvez appeler l'interface Envoi de code de vérification personnalisé EngageLab OTP.

Adresse d'appel

POST https://otp.api.engagelab.cc/v1/messages

Authentification

Veuillez consulter Authentification pour savoir comment effectuer l'authentification de l'API.

Exemple de requête

En-tête de la requête

              
              POST /v1/messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            

Corps de la requête

              
              {
    "to": "+6591234567",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

            

Paramètres de requête

Un objet de requête est exprimé au format JSON ; l'en-tête de la requête doit donc inclure Content-Type: application/json.

Remarques concernant params

1. Pour les champs prédéfinis dans le modèle, tels que from_id, si aucune valeur n'est transmise dans le champ params, le from_id prédéfini du modèle est utilisé lors de l'envoi du message ;
2. Si une valeur du champ params est transmise, comme params:{"from_id":"12345"}, le from_id du modèle sera remplacé par 12345 lors de l'envoi du message ;
3. De même, les champs de variables personnalisées définis dans le contenu du modèle lors de sa création se voient également attribuer une valeur via params : par exemple, pour un contenu de modèle Hi {{name}}, your verify code is {{code}}, vous devez attribuer le paramètre params:{"name":"Bob"}
4. Variables spéciales du canal Email : pour le canal Email, vous pouvez remplacer dynamiquement l'objet de l'e-mail (subject), le nom de l'expéditeur (from_name), l'adresse e-mail de l'expéditeur (from_mail), etc., via params. Pour les usages avancés détaillés, veuillez consulter Créer un modèle - Usage avancé des variables de modèle Email.

Paramètres de réponse

Réponse en cas de succès

              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

            

Notez que la valeur**send_channel**renvoyée ne représente pas le canal final de livraison à l'utilisateur, mais uniquement le canal utilisé à ce stade ; par exemple, si la stratégie configurée dans le modèle prévoit qu'en cas d'échec de livraison sur le canal WhatsApp, un renvoi automatique est effectué sur le canal SMS, l'interface renverra la valeur whatsapp. Une fois l'échec de livraison détecté après un certain délai, le système enverra le message via le canal SMS.

Réponse en cas d'échec

Le code de statut HTTP est 4xx ou 5xx, et le corps de la réponse contient les champs suivants :

              
              {
    "code": 5001,
    "message": "sms send fail"
}

            

Codes d'erreur

Le tableau ci-dessous décrit uniquement les erreurs renvoyées par cette API lors de l'authentification, de la validation avant envoi et de la soumission synchrone. Les échecs de livraison asynchrones après acceptation par le fournisseur ne sont pas renvoyés par cette API ; obtenez-les via une requête d'état du message ou des callbacks.

L'appelant doit utiliser code pour déterminer le type d'erreur. Utilisez message pour afficher la raison concrète ou pour le diagnostic ; ne vous fiez pas à un texte fixe de message pour la logique métier.

Notes sur les erreurs de limitation de débit et de volume d'envoi

• 3004 est le contrôle de fréquence d'envoi OTP par modèle ; la fenêtre de limite dépend de la configuration du modèle et peut ne pas correspondre à la durée de validité du code.
• 6001 et 6002 sont des contrôles de fréquence de sécurité au niveau du numéro ou de l'IP de l'utilisateur final.
• 6003 et 6008 indiquent que cette requête a atteint une limite de volume d'envoi ; après atteinte de la limite et passage en état suspendu, les requêtes suivantes peuvent renvoyer 6007.
• En cas de HTTP 429, ne réessayez pas immédiatement en boucle ; réessayez plus tard et, si le problème persiste, contactez un administrateur ou le support technique.
• 5011 à 5019 ne couvrent que les échecs identifiables lors de la soumission synchrone. Les statuts tels que numéro vide, téléphone éteint ou refus de l'opérateur après acceptation par le fournisseur peuvent encore être renvoyés via l'état asynchrone du message ou les callbacks.