Skip to content
Documentation Wasel

14 — API Externe: Templates et OTP

1. Objectif métier

Section titled “1. Objectif métier”

Permettre à vos systèmes externes (site e-commerce, CRM, portail client, service d’authentification) de:

  • déclencher des envois template WhatsApp,
  • envoyer et valider des codes OTP,
  • garder une traçabilité opérationnelle côté WASEL.

2. Qui utilise ce module (admin/operator)

Section titled “2. Qui utilise ce module (admin/operator)”
  • admin: pilote les clés, valide les templates, définit les règles OTP et supervise les résultats.
  • operator: suit les effets en production (échecs, confirmations, cas clients à reprendre).

3. Prérequis

Section titled “3. Prérequis”

Avant utilisation:

  • configuration WhatsApp organisation active,
  • clé externe active avec le bon périmètre,
  • template(s) approuvé(s) pour les envois transactionnels,
  • politique OTP validée (durée de validité, tentatives max, gestion des relances),
  • scénario de support prévu pour les échecs de vérification.

Contraintes importantes:

  • envoi en lot plafonné à 500 destinataires par opération,
  • OTP borné sur la durée de validité et le nombre de tentatives,
  • une nouvelle émission OTP remplace le code en attente précédent pour le même contact,
  • les variables template doivent être cohérentes avec le template approuvé.

4. Procédure pas-à-pas (orientée actions produit)

Section titled “4. Procédure pas-à-pas (orientée actions produit)”
  1. Valider le cas d’usage externe.
  • Notification transactionnelle unitaire,
  • diffusion sur petit lot,
  • authentification OTP.
  1. Préparer un test pilote.
  • 1 numéro interne,
  • 1 template validé,
  • 1 scénario OTP complet.
  1. Exécuter un envoi template unitaire.
  • Vérifier rendu, langue, et données injectées.
  • Contrôler la traçabilité du message côté WASEL.
  1. Exécuter un envoi template en lot.
  • Démarrer sur un lot restreint.
  • Vérifier taux de succès et erreurs avant montée de volume.
  1. Configurer et lancer le flux OTP.
  • Définir durée de validité,
  • définir nombre maximal d’essais,
  • choisir le mode d’affichage du code (copie directe, bouton, ou sans bouton).
  1. Vérifier un OTP côté parcours client.
  • Tester succès,
  • tester code faux,
  • tester expiration,
  • tester dépassement d’essais.
  1. Contrôler l’état OTP en support.
  • Consulter le dernier statut connu pour aider rapidement le client.
  1. Passer en production progressive.
  • D’abord petit volume,
  • puis extension après stabilisation.

5. Scénarios concrets (minimum 2)

Section titled “5. Scénarios concrets (minimum 2)”

  • Scénario A (confirmation commande):

    • le site envoie une confirmation template à l’unité,
    • la conversation client reste traçable,
    • l’équipe support retrouve facilement l’envoi.

  • Scénario B (lot transactionnel):

    • envoi d’une notification de livraison à un lot clients,
    • suivi des réussites/échecs,
    • relance ciblée uniquement sur échecs pertinents.

  • Scénario C (authentification OTP):

    • émission OTP,
    • saisie client,
    • vérification et retour d’état,
    • relance si nécessaire dans les limites de sécurité.

6. Erreurs fréquentes et résolution

Section titled “6. Erreurs fréquentes et résolution”

  • Problème: envoi template refusé.

  • Causes fréquentes: template non approuvé, variables incomplètes, configuration WhatsApp incomplète.

  • Résolution: vérifier d’abord l’état template puis la complétude des données.

  • Problème: échecs en lot au-delà d’un certain volume.

  • Causes fréquentes: données destinataires hétérogènes, surcharge opérationnelle.

  • Résolution: réduire la taille de lot, corriger la qualité des données, remonter progressivement.

  • Problème: OTP introuvable ou invalide.

  • Causes fréquentes: référence non cohérente, code expiré, tentatives dépassées.

  • Résolution: contrôler le statut OTP puis relancer un nouveau code si autorisé.

  • Problème: client reçoit un code mais ne peut pas valider.

  • Cause fréquente: confusion entre ancienne et nouvelle tentative OTP.

  • Résolution: redonner un code propre et expliciter la validité temporelle.

7. Bonnes pratiques et limites

Section titled “7. Bonnes pratiques et limites”
  • Séparer les usages transactionnels et OTP par clé dédiée.
  • Limiter les premiers envois à des volumes pilotes.
  • Utiliser un identifiant de référence pour distinguer les parcours simultanés (connexion, checkout, etc.).
  • Préparer des scripts opérateurs pour expliquer les motifs OTP les plus courants.
  • Surveiller quotidiennement les échecs sur les premières semaines d’exploitation.

Limites:

  • le volume par opération en lot reste borné,
  • la qualité des données destinataires impacte directement la délivrabilité,
  • un OTP est volontairement strict (durée et essais) pour des raisons de sécurité,
  • le premier usage OTP dans une nouvelle configuration peut prendre un peu plus de temps que les envois suivants.

8. Référence rapide (champs/statuts/modes)

Section titled “8. Référence rapide (champs/statuts/modes)”

Opérations couvertes:

  • envoi template unitaire,
  • envoi template en lot,
  • émission OTP,
  • vérification OTP,
  • consultation du dernier état OTP.

Paramètres OTP clés:

  • ttl_minutes (validité),
  • max_attempts (essais max),
  • button_type (copy_code, url, none),
  • reference (contexte métier).

Résultats OTP fréquents:

  • verified,
  • invalid_code,
  • expired,
  • max_attempts_exceeded,
  • not_found.

Traçabilité opérationnelle:

  • les envois externes sont rattachés à l’historique de messagerie,
  • des regroupements de suivi marketing peuvent être générés automatiquement pour lecture des résultats,
  • seul le code OTP en attente le plus récent est normalement vérifiable pour un même contexte client.

9. Liens vers modules liés

Section titled “9. Liens vers modules liés”