Envoyer des codes à usage unique sur WhatsApp avec l'API Flowella

Votre application crée un code à usage unique, l’envoie sur le WhatsApp du client avec l’API Flowella, puis vérifie le code saisi par le client. Le message utilise un modèle d’authentification avec un bouton de copie de code. Le rôle de HubSpot est facultatif : votre application peut enregistrer le résultat sur le contact.

Un workflow HubSpot ne peut pas envoyer de codes à usage unique. L’action Send WhatsApp Template de Flowella ne peut pas attribuer une valeur différente à un bouton OTP ou de copie de code pour chaque contact, et HubSpot ne doit pas conserver les codes. Envoyez plutôt les codes depuis votre application avec l’API.

En bref

Élément	Détails
Déclencheur	Une connexion ou une action sensible dans votre application
Flowella	`POST /v1/templates/send` avec des `buttonParameters` propres à chaque destinataire
Modèle	Un modèle d’authentification avec un bouton de copie de code (Authentication)
HubSpot	Facultatif. Votre application enregistre le résultat sur le contact, jamais le code
Calendrier	Code envoyé immédiatement. Autorisez un renvoi au plus tôt 15 secondes plus tard

Fonctionnement

Le diagramme montre une tentative de connexion, de la demande de code jusqu’à la connexion ou au verrouillage.

Avant de commencer

Créez une clé API. Consultez Clés API. Ce point de terminaison n’accepte que les clés API, pas les jetons d’accès OAuth.
Recueillez le numéro WhatsApp de chaque client au format international, par exemple +447700900123, ainsi que son accord pour recevoir des codes sur WhatsApp. Consultez les recommandations de Meta sur l’opt-in.
Lisez l’introduction à l’API pour l’authentification, les erreurs et les limites de débit.

Créer le modèle

Créez le modèle dans le WhatsApp Manager de Meta, avec la catégorie Authentication et un bouton de copie de code. Seuls les modèles d’authentification peuvent contenir un code à usage unique, et ils nécessitent un bouton de copie de code ou un bouton à appui unique. Meta impose la formulation : “<code> is your verification code.” Vous pouvez ajouter un rappel de ne pas partager le code et une ligne d’expiration de 1 à 90 minutes. Les URL, les médias et les emojis ne sont pas autorisés, et le code peut comporter jusqu’à 15 caractères. Une fois que Meta a approuvé le modèle, il apparaît dans Flowella. Consultez les règles de catégorisation des modèles de Meta et la page sur les modèles d’authentification avec copie de code. Si vous écrivez aussi aux clients au sujet d’un verrouillage, utilisez un modèle Utility distinct, par exemple

Hi {{1}}, we have paused sign-in to your account after several incorrect codes. Try again in 30 minutes or contact our support team.

Une alerte de sécurité du compte sans promotion relève de la catégorie Utility.

Envoyer un code

Trouver le modèle et le canal

Appelez GET /v1/templates?status=APPROVED. Notez l’id et le wabaId de votre modèle, ainsi que le whatsappChannelId du numéro depuis lequel vous envoyez. Consultez Multi-canal si vous avez plusieurs numéros.

Créer le code dans votre application

Générez un code aléatoire de 15 caractères au maximum. Stockez-en un hachage avec une courte expiration, et marquez-le comme à usage unique.

Envoyer la requête

Insérez le code deux fois : une fois comme paramètre du corps et une fois comme valeur du bouton de copie de code. Le format d’envoi de Meta traite le bouton de copie de code comme un bouton URL : utilisez donc subType url, avec index 0 pour le premier bouton.

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY" \
  -H "Idempotency-Key: otp-7f3c2a91" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "1234567890123456",
    "templateWabaId": "102290129340398",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [
      {
        "phone": "+447700900123",
        "bodyParameters": ["482913"],
        "buttonParameters": [
          { "index": 0, "subType": "url", "text": "482913" }
        ]
      }
    ]
  }'

Une réponse 202 avec "status": "accepted" signifie que Flowella a mis l’envoi en file d’attente. Elle ne confirme pas la distribution.

Vérifier le code

Lorsque le client saisit le code, comparez-le au hachage stocké. Acceptez-le une seule fois, et uniquement avant son expiration.

Gérer les renvois et le verrouillage

Envoyez un nouveau code à chaque tentative et invalidez l’ancien. Attendez au moins 15 secondes avant un renvoi : Flowella ignore un second envoi du même modèle au même numéro dans un délai de 15 secondes. Limitez le nombre de tentatives, puis verrouillez la connexion pendant une durée définie et proposez le support.

Enregistrer le résultat dans HubSpot (facultatif)

Faites mettre à jour le contact HubSpot par votre application via l’API de HubSpot, par exemple Last WhatsApp verification (sélecteur de date et d’heure) et Last verification result (liste déroulante : Passed, Failed, Locked). Un workflow HubSpot peut ensuite créer une tâche lorsque le résultat est Locked. Ne stockez jamais de codes dans HubSpot.

Utilisez une nouvelle Idempotency-Key pour chaque code, par exemple votre propre ID de vérification. Une répétition avec la même clé dans un délai de 7 jours renvoie l’id d’origine et n’envoie rien.

Tester l’intégration

Envoyez un code à votre propre numéro WhatsApp et vérifiez que le bouton de copie de code le copie bien.
Saisissez un code erroné, puis demandez un renvoi après le délai d’attente, et vérifiez que l’ancien code ne fonctionne plus.
Suivez la distribution avec les événements webhook message.delivered et message.failed. Consultez Webhooks.

Dépannage

Symptôme	Cause	Solution
Réponse `401`	La clé est absente ou invalide, ou vous avez utilisé un jeton d’accès OAuth	Utilisez une clé API valide. Consultez Clés API.
Réponse `429`	Vous avez dépassé la limite de débit	Attendez la durée indiquée dans l’en-tête `Retry-After`, puis réessayez.
Un renvoi n’arrive jamais	Il a été envoyé moins de 15 secondes après le code précédent, ou a réutilisé une `Idempotency-Key`	Attendez 15 secondes et utilisez une nouvelle clé.
Aucun code n’arrive pour un client	Le numéro s’est désinscrit des messages de votre numéro WhatsApp	Le client peut envoyer `START` pour se réinscrire. Consultez Désinscriptions.
L’envoi échoue pour les codes longs	Le code dépasse 15 caractères	Utilisez un code plus court.

Pages associées

Introduction à l’API : authentification, idempotence, erreurs et limites de débit.
Référence des modèles : catégories de modèles et types de boutons.
Webhooks : recevez les événements de distribution de Flowella.

Premiers pas

Essentiels

Utiliser l'application

Paramètres

Configuration Meta et WhatsApp

Intégration HubSpot

Flows et campagnes

Référence API

Dépannage

Journal des modifications

Envoyer des codes à usage unique sur WhatsApp avec l'API Flowella

En bref

Fonctionnement

Avant de commencer

Créer le modèle

Envoyer un code

Tester l’intégration

Dépannage

Pages associées

​En bref

​Fonctionnement

​Avant de commencer

​Créer le modèle

​Envoyer un code

​Tester l’intégration

​Dépannage

​Pages associées

En bref

Fonctionnement

Avant de commencer

Créer le modèle

Envoyer un code

Tester l’intégration

Dépannage

Pages associées