Verificación OTP por SMS

Resumen

Esta guía te muestra cómo integrar Twilio Verify 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, con la CLI de Agents o mediante la API de ElevenLabs.
• Autenticar ambas llamadas de webhook con una cabecera Authorization que incluya un valor secreto.
• Habilitar la herramienta del sistema 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 activado. Si Verify no está disponible en tu consola de Twilio, solicita acceso a través del soporte de Twilio o de tu equipo de cuenta de Twilio.
• Si tu cuenta de Twilio está en modo de prueba, el número de teléfono de destino debe ser un identificador de llamada verificado en Twilio.

Codifica las credenciales y configura las herramientas webhook

1

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.

En tu terminal, codifica en Base64 ACCOUNT_SID:AUTH_TOKEN (separados por dos puntos, sin espacios):

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.

Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==

2

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

Añadir desde la CLI

Añadir mediante la API

send_SMS_verification

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.

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.

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.

3

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

Añadir desde la CLI

Añadir mediante la API

En Tools, elige Add Tool, selecciona System tool y activa Skip turn. No necesitas realizar más configuraciones.

Añade indicaciones al prompt de sistema para que el modelo sepa cuándo llamarla; por ejemplo:

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 para obtener más información.

4

Orquesta el flujo en el prompt de sistema

Utiliza un prompt de sistema que secuencie claramente las herramientas; por ejemplo:

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:

{
  "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 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:

{
  "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 <base64> (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.

Otros problemas

• Número rechazado en modo de prueba: En la consola de Twilio, abre Números de teléfono verificados 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.