> 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. # Verificación OTP por SMS ![Conversación con un agente que recopila un número de teléfono, un código OTP y confirma la verificación](/docs/_fern-img/97201c6fdad0c63900236b52726c867d3ff9405fdbd30725858f384653c95803.webp) ## Resumen Esta guía te muestra cómo integrar [Twilio Verify](https://www.twilio.com/docs/verify/api) con tu agente de ElevenLabs para que puedas enviar un OTP al número de teléfono de quien llama y verificar el código que te proporciona durante una conversación de voz en directo. Aprenderás a: * Crear un servicio de Twilio Verify y codificar tus credenciales en Base64 para la autenticación. * Configurar dos herramientas de webhook (`send_SMS_verification` y `check_SMS_verification`) en el [panel](https://elevenlabs.io/app/agents), con la [CLI de Agents](/docs/es/eleven-agents/operate/cli) o mediante la [API de ElevenLabs](/docs/es/api-reference/introduction). * Autenticar ambas llamadas de webhook con una cabecera `Authorization` que incluya un valor secreto. * Habilitar la herramienta del sistema [`skip_turn`](/docs/es/eleven-agents/customization/tools/system-tools/skip-turn) para que el agente espere cuando quien llama aún no haya recibido el código. ## Requisitos previos * Una cuenta de Twilio con [Twilio Verify](https://www.twilio.com/docs/verify/api) activado. Si Verify no está disponible en tu consola de Twilio, solicita acceso a través del [soporte de Twilio](https://support.twilio.com/) o de tu equipo de cuenta de Twilio. * Si tu cuenta de Twilio está en [modo de prueba](https://www.twilio.com/docs/guides/how-to-use-your-free-trial-account), el número de teléfono de destino debe ser un identificador de llamada verificado en Twilio. #### Inicia sesión en la consola de Twilio Abre la [consola de Twilio](https://console.twilio.com/). #### Crea un servicio Authenticate (Verify) En la barra lateral izquierda, elige **Add +** y crea un servicio **Authenticate** (Verify). #### Asigna un nombre al servicio Asígnale un nombre descriptivo (por ejemplo, `ElevenLabs OTP`). #### Copia el SID del servicio Verify Abre la página de **Settings** del servicio y copia el **Verify Service SID**. Empieza por `VA` y es distinto de tu Account SID. > **Warning** > > **Error habitual**: utiliza el **Verify Service SID** (`VA...`) del servicio Authenticate (Verify) en las URL de herramientas que aparecen a continuación. No incluyas tu **Account SID** (`AC...`) en la ruta. La API de Verify espera el SID del servicio en la URL; usar el Account SID genera errores de parámetro no válido `4xx`. Puedes usar el explorador de API de Twilio en la consola para probar las solicitudes antes de vincularlas a tu agente. ### Codifica las credenciales y configura las herramientas webhook #### Codifica tus credenciales de Twilio para la autenticación Basic Twilio Verify utiliza autenticación HTTP Basic con tu **Account SID** como nombre de usuario y tu **Auth Token** como contraseña. Encontrarás ambos en **Account Info**, en la página de inicio de la [consola de Twilio](https://console.twilio.com/). En tu terminal, codifica en Base64 `ACCOUNT_SID:AUTH_TOKEN` (separados por dos puntos, sin espacios): ```bash printf '%s' 'YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN' | base64 ``` Copia el resultado. El valor completo de la cabecera `Authorization` es la palabra `Basic`, un solo espacio y esa cadena Base64. Guárdalo como secreto de herramienta en los siguientes pasos. ```text Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx== ``` #### Configura las herramientas \`send_SMS_verification\` y \`check_SMS_verification\` `send_SMS_verification` llama a Twilio Verify para enviar una OTP por SMS. `check_SMS_verification` envía los dígitos que dice la persona que llama. Ambas requieren el mismo Verify Service SID y el mismo secreto de `Authorization`. #### Añadir desde el panel ### send_SMS_verification ![Conversación del agente recopilando un número de teléfono, un código OTP y una verificación correcta](/docs/_fern-img/9d72a753674c17481e99ea871b1b178cd7791f2da1ec3491ad4786c3fbc9a84e.webp) En la sección **Agent** de los ajustes de tu agente, elige **Add Tool** y selecciona **Webhook**. | Campo | Valor | | ----------- | ------------------------------------------------------------------------------- | | Nombre | `send_SMS_verification` | | Descripción | Envía un código de verificación OTP por SMS al número de teléfono proporcionado | | Método | `POST` | | URL | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications` | Sustituye `YOUR_VERIFY_SERVICE_SID` por el SID `VA...` del primer paso. **Cabecera de autenticación:** en **Headers**, añade `Authorization` como tipo **Secret** y pega el valor completo (`Basic ` más Base64). Consulta [Herramientas webhook](/docs/es/eleven-agents/customization/tools/webhook-tools). **Parámetros del cuerpo:** establece **Content type** en **URL-encoded** (`application/x-www-form-urlencoded`). Añade parámetros con **LLM Prompt** como tipo de valor: | Tipo de datos | Identificador | Descripción | | ------------- | ------------- | ----------------------------------------------------------------------------------------- | | `string` | `To` | Número de teléfono de la persona que llama en formato E.164 (por ejemplo, `+14155552671`) | | `string` | `Channel` | Canal de entrega; usa `sms` | ### check_SMS_verification Añade una segunda herramienta webhook: | Campo | Valor | | ----------- | --------------------------------------------------------------------------------- | | Nombre | `check_SMS_verification` | | Descripción | Comprueba si el código OTP proporcionado por la persona que llama es válido | | Método | `POST` | | URL | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck` | Utiliza el mismo Verify Service SID y el mismo secreto de `Authorization` que para `send_SMS_verification`. **Parámetros del cuerpo:** **URL-encoded**. Añade `To` (E.164) y `Code` (dígitos de la OTP) con **LLM Prompt**. #### Añadir desde la CLI > **Note** > > Crea un [secreto de espacio de trabajo](/docs/es/api-reference/workspace/secrets/create) cuyo valor sea la cabecera completa de `Authorization` (`Basic ` más Base64). Incluye el ID del secreto en el JSON de abajo como `YOUR_SECRET_ID`. #### Añade los archivos de configuración de las herramientas Guarda la herramienta de envío como `tool_configs/send_SMS_verification.json` (sustituye `YOUR_VERIFY_SERVICE_SID` por tu 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" } } } } } ``` Guarda la herramienta de comprobación como `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 las herramientas ```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 ``` #### Vincula las herramientas a tu agente Edita `agent_configs/.json`. En `conversation_config.agent.prompt`, configura `tool_ids` para incluir ambas herramientas (utiliza los ID de `tools.json` o de `elevenlabs agents tools list`). Después, publícalo: ```bash elevenlabs agents push --agent "" ``` #### Añadir mediante la API > **Note** > > Crea un [secreto de espacio de trabajo](/docs/es/api-reference/workspace/secrets/create) que contenga el valor completo de la cabecera `Basic ...` y, después, pasa su ID como `secret_id` en `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** > > Si configuras **`Channel`** como un campo rellenado por el LLM en el panel, añade instrucciones en tu prompt de sistema para que el modelo siempre pase `sms`. Los ejemplos de CLI y API anteriores fijan `sms` con `constant_value` / `constantValue`, por lo que el modelo no elige el canal. #### Activa la herramienta de sistema \`skip_turn\` Las personas que llaman suelen necesitar un momento para recibir el SMS antes de poder leer el código. Sin `skip_turn`, el agente podría hablar durante la pausa o repetir indicaciones. #### Añadir desde el panel En **Tools**, elige **Add Tool**, selecciona **System tool** y activa **Skip turn**. No necesitas realizar más configuraciones. #### Añadir desde la CLI En `agent_configs/.json`, dentro de `conversation_config.agent.prompt`, establece `built_in_tools.skip_turn` en `null` (valores predeterminados) para activar Skip turn y, después, ejecuta: ```bash elevenlabs agents push --agent "" ``` #### Añadir mediante la 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, }, }, }, }, }); ``` Si ya configuraste `tool_ids` al crear las herramientas webhook, integra `built_in_tools` en el mismo objeto `prompt` en lugar de sustituirlo. Añade indicaciones al prompt de sistema para que el modelo sepa cuándo llamarla; por ejemplo: ```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. ``` Consulta [Skip turn](/docs/es/eleven-agents/customization/tools/system-tools/skip-turn) para obtener más información. #### Orquesta el flujo en el prompt de sistema Utiliza un prompt de sistema que secuencie claramente las herramientas; por ejemplo: ```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. ``` ## Resolución de problemas ### Twilio `60200` — Parámetro no válido (HTTP 400) Twilio puede devolver un cuerpo como este cuando la URL o el cuerpo de la solicitud no coinciden con lo que espera la API Verify: ```json { "code": 60200, "message": "Invalid parameter", "more_info": "https://www.twilio.com/docs/errors/60200", "status": 400 } ``` **Qué revisar:** La ruta debe usar el **SID del servicio Verify** (`VA...`) de la configuración del servicio Authenticate (Verify). Incluir tu **SID de cuenta** (`AC...`) en `.../Services/{Sid}/...` es una causa habitual del error `60200`. Consulta la documentación de Twilio sobre [60200](https://www.twilio.com/docs/errors/60200) para ver otros casos de parámetros no válidos. ### Twilio `20003` — Error de autenticación — No se proporcionaron credenciales (HTTP 401) Cuando falta el encabezado `Authorization`, tiene un formato incorrecto o no se envía, Twilio puede responder con: ```json { "code": 20003, "message": "Authentication Error - No credentials provided", "more_info": "https://www.twilio.com/docs/errors/20003", "status": 401 } ``` **Qué revisar:** La herramienta debe enviar un encabezado `Authorization` cuyo valor sea la cadena completa `Basic ` (incluida la palabra `Basic` y un único espacio antes de la salida Base64). La entrada de Base64 debe ser exactamente `ACCOUNT_SID:AUTH_TOKEN`, sin espacios ni saltos de línea adicionales. Confirma que el secreto esté asociado a este encabezado en ambas herramientas de webhook. Consulta [20003](https://www.twilio.com/docs/errors/20003). ### Otros problemas * **Número rechazado en modo de prueba:** En la consola de Twilio, abre [Números de teléfono verificados](https://console.twilio.com/us1/develop/phone-numbers/manage/verified) y asegúrate de que el número de destino aparezca en la lista antes de hacer la prueba. * **El agente habla encima de la persona que llama:** Confirma que **Omitir turno** esté activado y que el prompt del sistema indique al modelo que use `skip_turn` cuando la persona que llama necesite tiempo.