Vérification OTP par SMS

Vue d’ensemble

Ce guide explique comment intégrer Twilio Verify à votre agent ElevenLabs afin d’envoyer un OTP au numéro de téléphone d’un appelant et de vérifier le code qu’il vous communique lors d’une conversation vocale en direct.

Vous apprendrez à :

• Créer un service Twilio Verify et encoder vos identifiants en Base64 pour l’authentification.
• Configurer deux outils webhook, send_SMS_verification et check_SMS_verification, dans le dashboard, avec l’Agents CLI ou à l’aide de l’API ElevenLabs.
• Authentifier les deux appels webhook à l’aide d’un en-tête Authorization contenant une valeur secrète.
• Activer l’outil système skip_turn afin que l’agent attende lorsque l’appelant n’a pas encore reçu le code.

Prérequis

• Un compte Twilio avec Twilio Verify activé. Si Verify n’est pas disponible dans votre console Twilio, demandez l’accès via l’assistance Twilio ou votre équipe de compte Twilio.
• Si votre compte Twilio est en mode d’essai, le numéro de téléphone de destination doit être un ID appelant vérifié dans Twilio.

Encoder les identifiants et configurer les outils webhook

1

Encodez vos identifiants Twilio pour l’authentification Basic

Twilio Verify utilise l’authentification HTTP Basic avec votre Account SID comme nom d’utilisateur et votre Auth Token comme mot de passe. Vous les trouverez tous deux dans Account Info, sur la page d’accueil de la console Twilio.

Dans votre terminal, encodez ACCOUNT_SID:AUTH_TOKEN en Base64, séparés par deux-points et sans espaces :

printf '%s' 'YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN' | base64

Copiez la sortie. La valeur complète de l’en-tête Authorization se compose du mot Basic, d’un espace, puis de cette chaîne Base64. Enregistrez-la comme secret d’outil lors des prochaines étapes.

Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==

2

Configurez les outils send_SMS_verification et check_SMS_verification

send_SMS_verification appelle Twilio Verify pour envoyer un OTP par SMS. check_SMS_verification transmet les chiffres énoncés par l’appelant. Les deux requièrent le même Verify Service SID et le même secret Authorization.

Ajouter via le Dashboard

Ajouter via la CLI

Ajouter via l’API

send_SMS_verification

Dans la section Agent des paramètres de votre agent, sélectionnez Add Tool, puis Webhook.

Champ	Valeur
Nom	send_SMS_verification
Description	Envoie un code de vérification OTP par SMS au numéro de téléphone fourni
Méthode	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications

Remplacez YOUR_VERIFY_SERVICE_SID par le SID VA... de la première étape.

En-tête d’authentification : sous Headers, ajoutez Authorization en tant que type Secret et collez la valeur complète (Basic suivi de Base64). Consultez Outils webhook.

Paramètres du corps : définissez Content type sur URL-encoded (application/x-www-form-urlencoded). Ajoutez les paramètres avec LLM Prompt comme type de valeur :

Type de données	Identifiant	Description
string	To	Numéro de téléphone de l’appelant au format E.164, par exemple +14155552671
string	Channel	Canal de livraison ; utilisez sms

check_SMS_verification

Ajoutez un deuxième outil webhook :

Champ	Valeur
Nom	check_SMS_verification
Description	Vérifie si le code OTP fourni par l’appelant est valide
Méthode	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck

Utilisez le même Verify Service SID et le même secret Authorization que pour send_SMS_verification.

Paramètres du corps : URL-encoded. Ajoutez To (E.164) et Code (chiffres OTP) avec LLM Prompt.

Si vous configurez Channel comme champ renseigné par le LLM dans le Dashboard, ajoutez des instructions à votre prompt système afin que le modèle transmette toujours sms. Les exemples CLI et API ci-dessus définissent sms avec constant_value / constantValue, le modèle ne choisit donc pas le canal.

3

Activez l’outil système skip_turn

Les appelants ont souvent besoin d’un moment pour recevoir le SMS avant de pouvoir lire le code. Sans skip_turn, l’agent peut parler pendant ce silence ou répéter les invites.

Ajouter via le Dashboard

Ajouter via la CLI

Ajouter via l’API

Dans Tools, sélectionnez Add Tool, puis System tool, et activez Skip turn. Aucune autre configuration n’est requise.

Ajoutez des consignes au prompt système afin que le modèle sache quand l’appeler, par exemple :

When the caller indicates they are still waiting to receive the OTP code — for example,
"hold on", "I haven't received it yet", or "give me a second" — use the skip_turn tool
to wait silently rather than speaking. Do not repeat the prompt or ask for the code again
until the caller indicates they are ready.

Consultez Skip turn pour plus de détails.

4

Orchestrez le flux dans le prompt système

Utilisez un prompt système qui séquence clairement les outils, par exemple :

You are a secure verification agent. When you need to verify a caller's identity:
1. Ask for their phone number if you do not already have it.
2. Standardize the number to E.164 for tool calls: a leading plus, country code, then digits only, no spaces (for example +14155552671).
3. Call send_SMS_verification with their number and Channel set to "sms".
4. Tell the caller: "I've sent a verification code to your phone. Please read it out when you're ready."
5. If the caller says they haven't received the code yet or asks for a moment, use skip_turn to wait silently.
6. Once the caller provides the code, call check_SMS_verification with their number and the code.
7. If the response status is "approved", proceed with the verified flow.
8. If the code is invalid, let the caller know and offer to resend.

Résolution des problèmes

Twilio 60200 : paramètre non valide (HTTP 400)

Twilio peut renvoyer un corps de réponse comme celui-ci lorsque l’URL ou le corps de la requête ne correspond pas aux attentes de l’API Verify :

{
  "code": 60200,
  "message": "Invalid parameter",
  "more_info": "https://www.twilio.com/docs/errors/60200",
  "status": 400
}

À vérifier : le chemin doit utiliser votre Verify Service SID (VA...) issu des paramètres du service Authenticate (Verify). Insérer votre Account SID (AC...) dans .../Services/{Sid}/... est une cause fréquente de l’erreur 60200. Consultez la documentation Twilio sur 60200 pour les autres cas de paramètre non valide.

Twilio 20003 : erreur d’authentification : aucun identifiant fourni (HTTP 401)

Lorsque l’en-tête Authorization est absent, mal formé ou non envoyé, Twilio peut répondre par :

{
  "code": 20003,
  "message": "Authentication Error - No credentials provided",
  "more_info": "https://www.twilio.com/docs/errors/20003",
  "status": 401
}

À vérifier : l’outil doit envoyer un en-tête Authorization dont la valeur est la chaîne complète Basic <base64>, y compris le mot Basic et un seul espace avant la sortie Base64. L’entrée Base64 doit être exactement ACCOUNT_SID:AUTH_TOKEN, sans espaces ni sauts de ligne supplémentaires. Vérifiez que le secret est associé à cet en-tête sur les deux outils webhook. Consultez 20003.

Autres problèmes

• Numéro refusé en mode d’essai : dans la console Twilio, ouvrez Verified phone numbers et assurez-vous que le numéro de destination est répertorié avant de tester.
• L’agent parle en même temps que l’appelant : vérifiez que Skip turn est activé et que le prompt système indique au modèle d’utiliser skip_turn lorsque l’appelant a besoin de temps.