Verifica OTP via SMS

Panoramica

Questa guida mostra come integrare Twilio Verify con il tuo agente ElevenLabs per inviare un OTP al numero di telefono di un chiamante e verificare il codice che ti comunica durante una conversazione vocale in tempo reale.

Imparerai a:

• Creare un servizio Twilio Verify e codificare in Base64 le tue credenziali per l’autenticazione.
• Configurare due strumenti webhook (send_SMS_verification e check_SMS_verification) nella dashboard, con la CLI Agents o usando l’API ElevenLabs.
• Autenticare entrambe le chiamate webhook usando un header Authorization con un valore segreto.
• Abilitare lo strumento di sistema skip_turn affinché l’agente attenda quando il chiamante non ha ancora ricevuto il codice.

Prerequisiti

• Un account Twilio con Twilio Verify abilitato. Se Verify non è disponibile nella Twilio Console, richiedi l’accesso tramite il supporto Twilio o il team responsabile del tuo account Twilio.
• Se il tuo account Twilio è in modalità di prova, il numero di telefono di destinazione deve essere un ID chiamante verificato in Twilio.

Codifica le credenziali e configura gli strumenti webhook

1

Codifica le tue credenziali Twilio per l'autenticazione Basic

Twilio Verify usa l’autenticazione HTTP Basic con il tuo Account SID come nome utente e l’Auth Token come password. Trovi entrambi in Account Info nella home page della Twilio Console.

Nella shell, codifica in Base64 ACCOUNT_SID:AUTH_TOKEN (separati da due punti, senza spazi):

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

Copia l’output. Il valore completo dell’header Authorization è la parola Basic, un singolo spazio e quella stringa Base64. Salvala come secret dello strumento nei passaggi successivi.

Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==

2

Configura gli strumenti send_SMS_verification e check_SMS_verification

send_SMS_verification chiama Twilio Verify per inviare un OTP via SMS. check_SMS_verification invia le cifre pronunciate dal chiamante. Entrambi richiedono lo stesso Verify Service SID e lo stesso secret Authorization.

Aggiungi dalla dashboard

Aggiungi tramite CLI

Aggiungi tramite l'API

send_SMS_verification

Nella sezione Agent delle impostazioni dell’agente, scegli Add Tool e seleziona Webhook.

Campo	Valore
Nome	send_SMS_verification
Descrizione	Invia un codice di verifica OTP via SMS al numero di telefono fornito
Metodo	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications

Sostituisci YOUR_VERIFY_SERVICE_SID con il SID VA... del primo passaggio.

Header di autenticazione: in Headers, aggiungi Authorization come tipo Secret e incolla il valore completo (Basic più Base64). Vedi Strumenti webhook.

Parametri del body: imposta Content type su URL-encoded (application/x-www-form-urlencoded). Aggiungi i parametri con LLM Prompt come tipo di valore:

Tipo di dati	Identificatore	Descrizione
string	To	Numero di telefono del chiamante in formato E.164 (ad esempio +14155552671)
string	Channel	Canale di consegna; usa sms

check_SMS_verification

Aggiungi un secondo strumento webhook:

Campo	Valore
Nome	check_SMS_verification
Descrizione	Verifica se il codice OTP fornito dal chiamante è valido
Metodo	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck

Usa lo stesso Verify Service SID e lo stesso secret Authorization di send_SMS_verification.

Parametri del body: URL-encoded. Aggiungi To (E.164) e Code (cifre OTP) con LLM Prompt.

Se configuri Channel come campo compilato dall’LLM nella dashboard, aggiungi istruzioni nel prompt di sistema affinché il modello passi sempre sms. Gli esempi CLI e API qui sopra fissano sms con constant_value / constantValue, quindi il modello non sceglie il canale.

3

Abilita lo strumento di sistema skip_turn

Spesso chi chiama ha bisogno di un momento per ricevere l’SMS prima di poter leggere il codice. Senza skip_turn, l’agente potrebbe parlare durante la pausa o ripetere i prompt.

Aggiungi dalla dashboard

Aggiungi tramite CLI

Aggiungi tramite l'API

In Tools, scegli Add Tool, seleziona System tool e abilita Skip turn. Non è necessaria alcuna ulteriore configurazione.

Aggiungi indicazioni al prompt di sistema affinché il modello sappia quando chiamarlo, ad esempio:

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.

Per i dettagli, vedi Skip turn.

4

Orchestra il flusso nel prompt di sistema

Usa un prompt di sistema che ordini chiaramente gli strumenti, ad esempio:

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.

Risoluzione dei problemi

Twilio 60200 — Parametro non valido (HTTP 400)

Twilio può restituire un body come questo quando l’URL o il body della richiesta non corrisponde a quanto previsto dall’API Verify:

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

Cosa verificare: il path deve usare il tuo Verify Service SID (VA...) dalle impostazioni del servizio Authenticate (Verify). Inserire il tuo Account SID (AC...) in .../Services/{Sid}/... è una causa frequente di 60200. Consulta la documentazione Twilio per 60200 per altri casi di parametri non validi.

Twilio 20003 — Errore di autenticazione — Nessuna credenziale fornita (HTTP 401)

Quando l’header Authorization è assente, non valido o non viene inviato, Twilio può rispondere con:

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

Cosa verificare: lo strumento deve inviare un header Authorization il cui valore sia la stringa completa Basic <base64> (inclusa la parola Basic e un singolo spazio prima dell’output Base64). L’input Base64 deve essere esattamente ACCOUNT_SID:AUTH_TOKEN, senza spazi aggiuntivi né nuove righe. Verifica che il secret sia associato a questo header in entrambi gli strumenti webhook. Vedi 20003.

Altri problemi

• Numero rifiutato in modalità di prova: nella Twilio Console, apri Verified phone numbers e assicurati che il numero di destinazione sia elencato prima del test.
• L’agente parla sopra il chiamante: verifica che Skip turn sia abilitato e che il prompt di sistema indichi al modello di usare skip_turn quando chi chiama ha bisogno di tempo.