> 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ção de OTP por SMS ![Conversa com agente coletando um número de telefone, código OTP e confirmação de verificação](/docs/_fern-img/97201c6fdad0c63900236b52726c867d3ff9405fdbd30725858f384653c95803.webp) ## Visão geral Este guia mostra como integrar o [Twilio Verify](https://www.twilio.com/docs/verify/api) 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](https://elevenlabs.io/app/agents), com a [CLI do Agents](/docs/pt/eleven-agents/operate/cli) ou usando a [API da ElevenLabs](/docs/pt/api-reference/introduction). * Autenticar as duas chamadas de webhook usando um cabeçalho `Authorization` com um valor secreto. * Ativar a ferramenta do sistema [`skip_turn`](/docs/pt/eleven-agents/customization/tools/system-tools/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](https://www.twilio.com/docs/verify/api) ativado. Se o Verify não estiver disponível no Twilio Console, solicite acesso pelo [suporte da Twilio](https://support.twilio.com/) ou pela equipe da sua conta Twilio. * Se a sua conta Twilio estiver no [modo de teste](https://www.twilio.com/docs/guides/how-to-use-your-free-trial-account), o número de telefone de destino deverá ser um identificador de chamadas verificado na Twilio. #### Faça login no Twilio Console Abra o [Twilio Console](https://console.twilio.com/). #### Crie um serviço Authenticate (Verify) Na barra lateral esquerda, selecione **Add +** e crie um serviço **Authenticate** (Verify). #### Nomeie o serviço Dê a ele um nome descritivo (por exemplo, `ElevenLabs OTP`). #### Copie o Verify Service SID Abra a página **Settings** do serviço e copie o **Verify Service SID**. Ele começa com `VA` e é diferente do seu Account SID. > **Warning** > > **Erro comum**: use o **Verify Service SID** (`VA...`) do serviço Authenticate (Verify) nos URLs das ferramentas abaixo. Não coloque seu **Account SID** (`AC...`) no caminho. A API Verify espera o SID do serviço no URL; usar o Account SID gera erros `4xx` de parâmetro inválido. Você pode usar o Twilio API Explorer no console para testar solicitações antes de vinculá-las ao seu agente. ### Codifique as credenciais e configure as ferramentas de webhook #### 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](https://console.twilio.com/). No seu shell, codifique `ACCOUNT_SID:AUTH_TOKEN` em Base64 (separados por dois-pontos, sem espaços): ```bash 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. ```text Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx== ``` #### 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 ### send_SMS_verification ![Conversa do agente coletando um número de telefone, código OTP e confirmação de verificação](/docs/_fern-img/9d72a753674c17481e99ea871b1b178cd7791f2da1ec3491ad4786c3fbc9a84e.webp) 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](/docs/pt/eleven-agents/customization/tools/webhook-tools). **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**. #### Adicionar pela CLI > **Note** > > Crie um [segredo do workspace](/docs/pt/api-reference/workspace/secrets/create) cujo valor seja o cabeçalho `Authorization` completo (`Basic ` mais Base64). Insira o ID do segredo no JSON abaixo como `YOUR_SECRET_ID`. #### Adicione os arquivos de configuração das ferramentas Salve a ferramenta de envio como `tool_configs/send_SMS_verification.json` (substitua `YOUR_VERIFY_SERVICE_SID` pelo seu 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" } } } } } ``` Salve a ferramenta de verificação 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" } } } } } ``` #### Registre as ferramentas ```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 ``` #### Vincule as ferramentas ao seu agente Edite `agent_configs/.json`. Em `conversation_config.agent.prompt`, defina `tool_ids` para incluir ambas as ferramentas (use os IDs de `tools.json` ou de `elevenlabs agents tools list`). Em seguida, envie: ```bash elevenlabs agents push --agent "" ``` #### Adicionar pela API > **Note** > > Crie um [segredo do workspace](/docs/pt/api-reference/workspace/secrets/create) que contenha o valor completo do cabeçalho `Basic ...` e passe o ID dele como `secret_id` em `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 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. #### 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 Em **Tools**, selecione **Add Tool**, escolha **System tool** e ative **Skip turn**. Nenhuma configuração adicional é necessária. #### Adicionar pela CLI Em `agent_configs/.json`, em `conversation_config.agent.prompt`, defina `built_in_tools.skip_turn` como `null` (padrões) para ativar Skip turn e, em seguida, execute: ```bash elevenlabs agents push --agent "" ``` #### Adicionar pela 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 você já tiver definido `tool_ids` ao criar as ferramentas de webhook, una `built_in_tools` ao mesmo objeto `prompt` em vez de substituí-lo. Adicione orientações ao prompt de sistema para que o modelo saiba quando chamá-la, por exemplo: ```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. ``` Consulte [Skip turn](/docs/pt/eleven-agents/customization/tools/system-tools/skip-turn) para ver os detalhes. #### Orquestre o fluxo no prompt de sistema Use um prompt de sistema que organize claramente a sequência das ferramentas, por exemplo: ```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. ``` ## 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: ```json { "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](https://www.twilio.com/docs/errors/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: ```json { "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 ` (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](https://www.twilio.com/docs/errors/20003). ### Outros problemas * **Número rejeitado no modo de teste:** No Console do Twilio, abra [Números de telefone verificados](https://console.twilio.com/us1/develop/phone-numbers/manage/verified) 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.