> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Verifica OTP via SMS ![Conversazione con un agente che raccoglie un numero di telefono, un codice OTP e la conferma della verifica](/docs/_fern-img/97201c6fdad0c63900236b52726c867d3ff9405fdbd30725858f384653c95803.webp) ## Panoramica Questa guida mostra come integrare [Twilio Verify](https://www.twilio.com/docs/verify/api) 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](https://elevenlabs.io/app/agents), con la [CLI Agents](/docs/it/eleven-agents/operate/cli) o usando l'[API ElevenLabs](/docs/it/api-reference/introduction). * Autenticare entrambe le chiamate webhook usando un header `Authorization` con un valore segreto. * Abilitare lo strumento di sistema [`skip_turn`](/docs/it/eleven-agents/customization/tools/system-tools/skip-turn) affinché l'agente attenda quando il chiamante non ha ancora ricevuto il codice. ## Prerequisiti * Un account Twilio con [Twilio Verify](https://www.twilio.com/docs/verify/api) abilitato. Se Verify non è disponibile nella Twilio Console, richiedi l'accesso tramite il [supporto Twilio](https://support.twilio.com/) o il team responsabile del tuo account Twilio. * Se il tuo account Twilio è in [modalità di prova](https://www.twilio.com/docs/guides/how-to-use-your-free-trial-account), il numero di telefono di destinazione deve essere un ID chiamante verificato in Twilio. #### Accedi alla Twilio Console Apri la [Twilio Console](https://console.twilio.com/). #### Crea un servizio Authenticate (Verify) Nella barra laterale sinistra, scegli **Add +** e crea un servizio **Authenticate** (Verify). #### Assegna un nome al servizio Assegnagli un nome descrittivo (ad esempio, `ElevenLabs OTP`). #### Copia il Verify Service SID Apri la pagina **Settings** del servizio e copia il **Verify Service SID**. Inizia con `VA` ed è diverso dal tuo Account SID. > **Warning** > > **Errore comune**: usa il tuo **Verify Service SID** (`VA...`) del servizio Authenticate (Verify) negli URL degli strumenti qui sotto. Non inserire il tuo **Account SID** (`AC...`) nel path. L'API Verify richiede il SID del servizio nell'URL; usando l'Account SID si generano errori `4xx` relativi a parametri non validi. Puoi usare Twilio API Explorer nella console per testare le richieste prima di collegarle al tuo agente. ### Codifica le credenziali e configura gli strumenti webhook #### 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](https://console.twilio.com/). Nella shell, codifica in Base64 `ACCOUNT_SID:AUTH_TOKEN` (separati da due punti, senza spazi): ```bash 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. ```text Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx== ``` #### 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 ### send\_SMS\_verification ![Conversazione dell'agente che raccoglie un numero di telefono, un codice OTP e la conferma della verifica](/docs/_fern-img/9d72a753674c17481e99ea871b1b178cd7791f2da1ec3491ad4786c3fbc9a84e.webp) 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](/docs/it/eleven-agents/customization/tools/webhook-tools). **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**. #### Aggiungi tramite CLI > **Note** > > Crea un [secret del workspace](/docs/it/api-reference/workspace/secrets/create) il cui valore sia l'header `Authorization` completo (`Basic ` più Base64). Inserisci l'ID del secret nel JSON qui sotto come `YOUR_SECRET_ID`. #### Aggiungi i file di configurazione degli strumenti Salva lo strumento di invio come `tool_configs/send_SMS_verification.json` (sostituisci `YOUR_VERIFY_SERVICE_SID` con il tuo SID `VA...`): ```json { "type": "webhook", "name": "send_SMS_verification", "description": "Sends an OTP verification code via SMS to the provided phone number", "api_schema": { "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications", "method": "POST", "content_type": "application/x-www-form-urlencoded", "request_headers": { "Authorization": { "secret_id": "YOUR_SECRET_ID" } }, "request_body_schema": { "type": "object", "description": "Twilio Verify start verification parameters", "required": ["To", "Channel"], "properties": { "To": { "type": "string", "description": "Caller phone number in E.164 format (for example +14155552671)" }, "Channel": { "type": "string", "constant_value": "sms" } } } } } ``` Salva lo strumento di verifica come `tool_configs/check_SMS_verification.json`: ```json { "type": "webhook", "name": "check_SMS_verification", "description": "Checks whether the OTP code provided by the caller is valid", "api_schema": { "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck", "method": "POST", "content_type": "application/x-www-form-urlencoded", "request_headers": { "Authorization": { "secret_id": "YOUR_SECRET_ID" } }, "request_body_schema": { "type": "object", "description": "Twilio Verify verification check parameters", "required": ["To", "Code"], "properties": { "To": { "type": "string", "description": "Same caller number in E.164 format" }, "Code": { "type": "string", "description": "The OTP digits the caller provided" } } } } } ``` #### Registra gli strumenti ```bash elevenlabs tools add "send_SMS_verification" --type "webhook" --config-path ./tool_configs/send_SMS_verification.json elevenlabs tools add "check_SMS_verification" --type "webhook" --config-path ./tool_configs/check_SMS_verification.json ``` #### Collega gli strumenti al tuo agente Modifica `agent_configs/.json`. In `conversation_config.agent.prompt`, imposta `tool_ids` in modo da includere entrambi gli strumenti (usa gli ID da `tools.json` o da `elevenlabs agents tools list`). Quindi esegui il push: ```bash elevenlabs agents push --agent "" ``` #### Aggiungi tramite l'API > **Note** > > Crea un [secret del workspace](/docs/it/api-reference/workspace/secrets/create) contenente il valore completo dell'header `Basic ...`, quindi passa il suo ID come `secret_id` in `request_headers`. ```python from elevenlabs import ElevenLabs, ToolRequestModel elevenlabs = ElevenLabs() send_sms = elevenlabs.conversational_ai.tools.create( request=ToolRequestModel( tool_config={ "type": "webhook", "name": "send_SMS_verification", "description": "Sends an OTP verification code via SMS to the provided phone number", "api_schema": { "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications", "method": "POST", "content_type": "application/x-www-form-urlencoded", "request_headers": { "Authorization": {"secret_id": "YOUR_SECRET_ID"}, }, "request_body_schema": { "type": "object", "description": "Twilio Verify start verification parameters", "required": ["To", "Channel"], "properties": { "To": { "type": "string", "description": "Caller phone number in E.164 format (for example +14155552671)", }, "Channel": { "type": "string", "constant_value": "sms", }, }, }, }, } ) ) check_sms = elevenlabs.conversational_ai.tools.create( request=ToolRequestModel( tool_config={ "type": "webhook", "name": "check_SMS_verification", "description": "Checks whether the OTP code provided by the caller is valid", "api_schema": { "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck", "method": "POST", "content_type": "application/x-www-form-urlencoded", "request_headers": { "Authorization": {"secret_id": "YOUR_SECRET_ID"}, }, "request_body_schema": { "type": "object", "description": "Twilio Verify verification check parameters", "required": ["To", "Code"], "properties": { "To": { "type": "string", "description": "Same caller number in E.164 format", }, "Code": { "type": "string", "description": "The OTP digits the caller provided", }, }, }, }, } ) ) elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", conversation_config={ "agent": { "prompt": { "tool_ids": [send_sms.id, check_sms.id], }, }, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); const sendSms = await elevenlabs.conversationalAi.tools.create({ toolConfig: { type: "webhook", name: "send_SMS_verification", description: "Sends an OTP verification code via SMS to the provided phone number", apiSchema: { url: "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications", method: "POST", contentType: "application/x-www-form-urlencoded", requestHeaders: { Authorization: { secretId: "YOUR_SECRET_ID" }, }, requestBodySchema: { type: "object", description: "Twilio Verify start verification parameters", required: ["To", "Channel"], properties: { To: { type: "string", description: "Caller phone number in E.164 format (for example +14155552671)", }, Channel: { type: "string", constantValue: "sms", }, }, }, }, }, }); const checkSms = await elevenlabs.conversationalAi.tools.create({ toolConfig: { type: "webhook", name: "check_SMS_verification", description: "Checks whether the OTP code provided by the caller is valid", apiSchema: { url: "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck", method: "POST", contentType: "application/x-www-form-urlencoded", requestHeaders: { Authorization: { secretId: "YOUR_SECRET_ID" }, }, requestBodySchema: { type: "object", description: "Twilio Verify verification check parameters", required: ["To", "Code"], properties: { To: { type: "string", description: "Same caller number in E.164 format", }, Code: { type: "string", description: "The OTP digits the caller provided", }, }, }, }, }, }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { toolIds: [sendSms.id, checkSms.id], }, }, }, }); ``` > **Note** > > 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. #### 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 In **Tools**, scegli **Add Tool**, seleziona **System tool** e abilita **Skip turn**. Non è necessaria alcuna ulteriore configurazione. #### Aggiungi tramite CLI In `agent_configs/.json`, in `conversation_config.agent.prompt`, imposta `built_in_tools.skip_turn` su `null` (valori predefiniti) per abilitare Skip turn, quindi esegui: ```bash elevenlabs agents push --agent "" ``` #### Aggiungi tramite l'API ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", conversation_config={ "agent": { "prompt": { "built_in_tools": { "skip_turn": None, }, }, }, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { builtInTools: { skipTurn: null, }, }, }, }, }); ``` Se hai già impostato `tool_ids` durante la creazione degli strumenti webhook, unisci `built_in_tools` allo stesso oggetto `prompt` anziché sostituirlo. Aggiungi indicazioni al prompt di sistema affinché il modello sappia quando chiamarlo, ad esempio: ```text 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](/docs/it/eleven-agents/customization/tools/system-tools/skip-turn). #### Orchestra il flusso nel prompt di sistema Usa un prompt di sistema che ordini chiaramente gli strumenti, ad esempio: ```text 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: ```json { "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](https://www.twilio.com/docs/errors/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: ```json { "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 ` (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](https://www.twilio.com/docs/errors/20003). ### Altri problemi * **Numero rifiutato in modalità di prova:** nella Twilio Console, apri [Verified phone numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/verified) 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.