Verificação de OTP por SMS

Visão geral

Este guia mostra como integrar o Twilio Verify ao seu agente da ElevenLabs para que você possa enviar um OTP ao número de telefone de quem liga e verificar o código informado durante uma conversa de voz ao vivo.

Você aprenderá a:

• Criar um serviço do Twilio Verify e codificar suas credenciais em Base64 para autenticação.
• Configurar duas ferramentas de webhook (send_SMS_verification e check_SMS_verification) no painel, com a CLI do Agents ou usando a API da ElevenLabs.
• Autenticar as duas chamadas de webhook usando um cabeçalho Authorization com um valor secreto.
• Ativar a ferramenta do sistema skip_turn para que o agente aguarde quando quem liga ainda não tiver recebido o código.

Pré-requisitos

• Uma conta Twilio com o Twilio Verify ativado. Se o Verify não estiver disponível no Twilio Console, solicite acesso pelo suporte da Twilio ou pela equipe da sua conta Twilio.
• Se a sua conta Twilio estiver no modo de teste, o número de telefone de destino deverá ser um identificador de chamadas verificado na Twilio.

Codifique as credenciais e configure as ferramentas de webhook

1

Codifique suas credenciais Twilio para autenticação Basic

O Twilio Verify usa autenticação HTTP Basic, com seu Account SID como nome de usuário e o Auth Token como senha. Encontre ambos em Account Info na página inicial do Twilio Console.

No seu shell, codifique ACCOUNT_SID:AUTH_TOKEN em Base64 (separados por dois-pontos, sem espaços):

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

Copie o resultado. O valor completo do cabeçalho Authorization é a palavra Basic, um único espaço e essa string Base64. Armazene-o como um segredo de ferramenta nas próximas etapas.

Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==

2

Configure as ferramentas send_SMS_verification e check_SMS_verification

send_SMS_verification chama o Twilio Verify para enviar um OTP por SMS. check_SMS_verification envia os dígitos informados pelo chamador. Ambas exigem o mesmo Verify Service SID e o mesmo segredo Authorization.

Adicionar pelo painel

Adicionar pela CLI

Adicionar pela API

send_SMS_verification

Na seção Agent das configurações do seu agente, selecione Add Tool e escolha Webhook.

Campo	Valor
Nome	send_SMS_verification
Descrição	Envia um código de verificação OTP por SMS para o número de telefone informado
Método	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications

Substitua YOUR_VERIFY_SERVICE_SID pelo SID VA... da primeira etapa.

Cabeçalho de autenticação: em Headers, adicione Authorization como tipo Secret e cole o valor completo (Basic mais Base64). Consulte Ferramentas de webhook.

Parâmetros do corpo: defina Content type como URL-encoded (application/x-www-form-urlencoded). Adicione parâmetros com LLM Prompt como tipo de valor:

Tipo de dados	Identificador	Descrição
string	To	Número de telefone do chamador no formato E.164 (por exemplo, +14155552671)
string	Channel	Canal de entrega; use sms

check_SMS_verification

Adicione uma segunda ferramenta de webhook:

Campo	Valor
Nome	check_SMS_verification
Descrição	Verifica se o código OTP informado pelo chamador é válido
Método	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck

Use o mesmo Verify Service SID e o mesmo segredo Authorization usados em send_SMS_verification.

Parâmetros do corpo: URL-encoded. Adicione To (E.164) e Code (dígitos do OTP) com LLM Prompt.

Se você configurar Channel como um campo preenchido pelo LLM no painel, adicione instruções ao seu prompt de sistema para que o modelo sempre passe sms. Os exemplos de CLI e API acima fixam sms com constant_value / constantValue, para que o modelo não escolha o canal.

3

Ative a ferramenta de sistema skip_turn

Os chamadores geralmente precisam de um momento para receber o SMS antes de poderem informar o código. Sem skip_turn, o agente pode falar durante a pausa ou repetir instruções.

Adicionar pelo painel

Adicionar pela CLI

Adicionar pela API

Em Tools, selecione Add Tool, escolha System tool e ative Skip turn. Nenhuma configuração adicional é necessária.

Adicione orientações ao prompt de sistema para que o modelo saiba quando chamá-la, por exemplo:

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.

Consulte Skip turn para ver os detalhes.

4

Orquestre o fluxo no prompt de sistema

Use um prompt de sistema que organize claramente a sequência das ferramentas, por exemplo:

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.

Solução de problemas

Twilio 60200 — Parâmetro inválido (HTTP 400)

O Twilio pode retornar um corpo como este quando a URL ou o corpo da solicitação não corresponde ao que a API Verify espera:

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

O que verificar: O caminho deve usar o SID do serviço Verify (VA...) nas configurações do serviço Authenticate (Verify). Inserir o SID da conta (AC...) em .../Services/{Sid}/... é uma causa comum do 60200. Consulte a documentação do Twilio sobre o 60200 para outros casos de parâmetro inválido.

Twilio 20003 — Erro de autenticação — Nenhuma credencial fornecida (HTTP 401)

Quando o cabeçalho Authorization está ausente, malformado ou não é enviado, o Twilio pode responder com:

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

O que verificar: A ferramenta deve enviar um cabeçalho Authorization cujo valor seja a string completa Basic <base64> (incluindo a palavra Basic e um único espaço antes da saída em Base64). A entrada em Base64 deve ser exatamente ACCOUNT_SID:AUTH_TOKEN, sem espaços extras ou quebras de linha. Confirme que o segredo está anexado a esse cabeçalho em ambas as ferramentas de webhook. Consulte 20003.

Outros problemas

• Número rejeitado no modo de teste: No Console do Twilio, abra Números de telefone verificados e confirme que o número de destino está listado antes de testar.
• O agente fala por cima de quem liga: Confirme que Skip turn está ativado e que o prompt do sistema instrui o modelo a usar skip_turn quando a pessoa precisar de tempo.