Tutorial completo de construção de um agente de chamadas outbound com…

INEMA

Aqui vão hacks práticos e diretos para esse tipo de automação com VAPI + agentes outbound, focados em escala, qualidade e menos bugs:

Hacks de Arquitetura⌗

Sempre use número Twilio, não só VAPI free → remove limite diário e melhora detecção de voicemail (ended_reason = voicemail).
Separar “Create Call” de “Get Call” → nunca tente ler dados da chamada no mesmo request.
Polling com limite → ex.: no máximo 10 tentativas, senão encerra e loga erro.
Node de “Limit = 1” após GET Call → evita bugs de múltiplos itens retornados pela API.

Hacks de Prompt / Agente⌗

Peça confirmação explícita

“Antes de continuar, confirme se este é realmente [NOME] da [EMPRESA]”

Force respostas curtas

“Responda em no máximo 2 frases.”

Ordem certa das perguntas

Interesse real
Problema atual
Urgência
Experiência passada
Orçamento

Nunca deixe o agente inventar
Incluir no prompt:

“Se você não souber, diga que não tem essa informação.”

Hacks de Structured Outputs⌗

Nunca confie só no transcript → sempre use structured outputs para:
interesse
urgência
orçamento
intenção paga
Use valores normalizados
urgência: low | medium | high
interesse: true | false
orçamento: número ou faixa

Hacks de Dados / Formulário⌗

Telefone como TEXTO, não número → evita perda de DDI, parênteses e zeros iniciais.
Validação antes da chamada
telefone inválido → não liga
e-mail inválido → marca para follow-up manual
Adicionar hidden fields
origem do lead
campanha
página de conversão

Hacks de Voicemail / Callback⌗

Não deixar voicemail automático
Desligar ou reduzir agressivamente voicemail detection.
Callback inteligente
Perguntar no prompt:

“Qual o melhor horário para ligar de volta?” * Salvar isso como structured output.

Hacks de Operação⌗

Delay aleatório antes de ligar → 5–30 segundos para parecer mais humano.
Horário comercial inteligente → só ligar entre 9h–18h do fuso do lead.
Fallback humano
Se erro de API → notificar time automaticamente.

Hacks de Escala⌗

Um agente, vários prompts → trocar só o system prompt via assistantOverrides.
Tags por status
incorrect_phone
callback
qualified
disqualified

Aí vai o passo a passo do processo, do início ao fim, bem direto:

Criar a planilha (Google Sheets)

Colunas: data, nome, telefone, e-mail, empresa, cargo, pedido, tamanho, interesse, motivação, urgência, experiência, orçamento, intenção paga, status.

Criar o formulário (ex.: n8n Form / site)

Campos mínimos: nome, telefone, e-mail, empresa, cargo, pedido, tamanho da empresa.

Trigger do workflow

“New form submission” (ou webhook do seu site).

Normalizar o telefone (Code Node – JavaScript)

Limpar tudo que não é número.
Validar se ficou com 10 dígitos (ou E.164 se preferir).
Se inválido → marcar como “incorrect phone”.

IF: telefone inválido?

Sim: gravar na planilha com status incorrect phone e encerrar.
Não: seguir.

Configurar o agente na VAPI

Modelo: GPT-4.
System prompt com variáveis (ex.: {{lead_name}}, {{lead_company_name}}, {{lead_request}}).
Perguntas de qualificação (interesse, motivação, urgência, experiência, orçamento, etc.).
Ativar Structured Outputs (campos que você quer receber no final).

(Opcional, recomendado) Usar número Twilio

Importar número Twilio na VAPI para:
escalar volume (sem limite dos números grátis)
detectar voicemail melhor (ended_reason = voicemail)

Chamar o lead (HTTP Request – POST create call)

Endpoint da VAPI: criar chamada.
Headers: Bearer API Key.
Body inclui:
assistantId
phoneNumberId (número que liga)
customer.number (número do lead com DDI)
assistantOverrides.variableValues (nome/empresa/pedido do form)

Esperar (Wait)

Aguardar alguns segundos (ex.: 10–60s) para a chamada acontecer.

Buscar detalhes da chamada (HTTP Request – GET call)

Usar o call_id retornado no create call.
Retorna status, ended_reason, transcript, structured outputs.

Polling: IF status != ended

Se ainda não terminou:
Wait (ex.: 10s)
GET call de novo
Repetir até status = ended.

IF: caiu em voicemail / não atendeu?

Se usando Twilio: checar ended_reason == voicemail.
Se voicemail → status callback.

Salvar no Google Sheets

Se callback: salvar dados do formulário + status callback (campos de qualificação ficam NA).
Se atendido: salvar dados do formulário + structured outputs (interesse, motivação, urgência, etc.) + status complete.

(Opcional) Ações depois do log

Se callback → notificar time (Slack/e-mail) ou agendar nova tentativa.
Se incorrect phone → pedir correção por e-mail.
Se complete → criar tarefa comercial / agendar discovery.

Recursos utilizados (direto e objetivo):

VAPI
Agente de voz outbound
API de chamadas (create call, get call)
Structured Outputs
Phone numbers (VAPI e Twilio)
OpenAI (GPT-4)
Modelo usado como “cérebro” do agente
Twilio
Número telefônico próprio para escalar chamadas
Detecção confiável de voicemail
Formulário (n8n / similar)
Coleta de leads (nome, telefone, e-mail, empresa, etc.)
JavaScript (Code Node)
Normalização e validação do número de telefone
Google Sheets
Registro dos leads
Status: completo, callback, telefone inválido
HTTP Requests
Integração direta com a API da VAPI
Autenticação Bearer
Lógica de Workflow
If / Else (decisão)
Wait + Polling (verificar status da chamada)
Filtros por status e ended_reason

O autor traz dois aprendizados importantes sobre o uso de chamadas outbound com a VAPI:

Limite de chamadas outbound com números da VAPI

A VAPI oferece até 10 números US gratuitos, mas existe um limite diário de chamadas outbound por conta, não por número.
Criar novos números da VAPI não contorna o limite.
Para escalar, é necessário importar um número próprio do Twilio.

Detecção mais confiável de voicemail com Twilio

Usando um número do Twilio, quando a chamada vai para a caixa postal, o ended_reason retorna explicitamente como voicemail.
Isso é mais confiável do que checar apenas mensagens como “your call has been forwarded to voicemail”.
Com isso, o fluxo pode ser simplificado para:
- Verificar se ended_reason == voicemail (em vez de “contains texto”).

Conclusão

Para escala e confiabilidade, usar Twilio + VAPI é a melhor opção.
Isso melhora tanto o volume de chamadas quanto a lógica de decisão no workflow (callback vs. chamada atendida).

Resumo do conteúdo

A construção, passo a passo, de um agente de chamadas outbound com VAPI, integrado a um formulário e a um Google Sheets, para qualificação automática de leads.

Objetivo do fluxo

Quando um lead preenche um formulário no site, o agente:

Valida e padroniza os dados (principalmente o telefone)
Liga automaticamente para o lead
Faz perguntas de qualificação
Registra tudo em uma planilha
Classifica o status do lead (completo, callback, telefone incorreto)

Principais etapas

Formulário de entrada Coleta nome, telefone, e-mail, empresa, cargo, pedido e tamanho da empresa.
Padronização do telefone (JavaScript)

Remove caracteres inválidos
Garante exatamente 10 dígitos
Telefones inválidos são registrados como “incorrect phone” e não recebem ligação.

Configuração do agente VAPI

Usa GPT-4
Recebe variáveis dinâmicas do formulário (nome, empresa, pedido)
Segue um roteiro de qualificação (interesse, urgência, motivação, experiência prévia, orçamento)
Gera structured outputs (dados estruturados da conversa)

Chamada via API da VAPI

Cria a chamada com POST /call * Usa autenticação Bearer
Passa número do lead + variáveis do formulário

Polling da chamada

O sistema espera e verifica repetidamente se a chamada terminou
Evita continuar o fluxo antes do fim da ligação

Tratamento de casos

** * Não atendeu / voicemail → status “callback” * Atendeu e conversou → status “complete” * Telefone inválido →** status “incorrect phone”

Registro no Google Sheets

Data e hora
Dados do lead
Respostas da qualificação (interesse, motivação, urgência, experiência, orçamento)
Status final

Aprendizados importantes

Necessidade de normalizar dados antes de usar APIs
Uso de variáveis dinâmicas no prompt do agente
Uso de structured outputs para transformar conversa em dados
Implementação de polling para lidar com chamadas assíncronas
Debugging prático de bugs reais da VAPI

Resultado final Um sistema completo e automatizado que:

Recebe leads
Liga automaticamente
Qualifica por voz com IA
Organiza tudo em planilha
Prepara o time para follow-up eficiente

É um exemplo avançado e realista de automação com agentes de voz.

Esse diagrama resume o fluxo completo do agente outbound mostrado no vídeo. Em termos simples:

1. Trigger – Form

O fluxo começa quando alguém preenche um formulário.
Dados coletados: nome, telefone, e-mail, empresa, cargo, pedido e tamanho da empresa.

2. Normalize data

Os dados (principalmente o telefone) são padronizados.
Garante que o número esteja em um formato válido antes de qualquer chamada.

3. Call Lead (1ª chamada)

O agente de voz (VAPI) liga para o lead usando os dados do formulário.
As informações do formulário são passadas como variáveis para o agente.

4. Wait

O sistema aguarda a ligação acontecer/terminar.
Necessário porque a chamada é assíncrona.

5. Call Lead (Get Call / verificação)

O workflow consulta a API para buscar o status e os dados da chamada (transcrição, structured outputs, etc.).

6. Prospect Answer?

Decisão:
Não atendeu → registra como callback / voicemail.
Atendeu → registra a qualificação completa.

7. Store Submission

Em ambos os casos, os dados são salvos (ex.: Google Sheets), com status adequado:
telefone inválido
callback
completo

Essência do fluxo

O formulário não serve só para coletar dados, mas para alimentar um agente de voz inteligente, que liga, qualifica o lead automaticamente e transforma a conversa em dados estruturados para o time comercial.

ap86- Agente de Chamadas com VAPI

chatgpt.com ↗