Atualizado em 29/10/2026
Para transferir do bot para um humano no WhatsApp, o seu sistema muda o estado da conversa de “bot” para “aguardando humano”, para de gerar respostas automáticas, avisa o cliente e entrega ao atendente um resumo com os dados já coletados. A transferência deve acontecer quando o cliente pede, quando o assunto é sensível, quando o bot falha duas vezes ou quando o cliente é prioritário. A política do WhatsApp Business permite automação dentro da janela de 24 horas, mas exige caminhos de escalonamento rápidos, claros e diretos.
A API oficial não tem um botão de “transferir”: quem faz o handoff é o seu software. Este guia mostra gatilhos, o que passar ao atendente, como pausar e devolver o bot, SLA e um pseudocódigo.
Por que o handoff é obrigatório, não opcional
A Política de Mensagens do WhatsApp Business diz que a empresa pode usar automação ao responder dentro da janela de 24 horas, desde que mantenha caminhos de escalonamento rápidos, claros e diretos. A lista de opções aceitas inclui:
- transferência para um atendente humano na própria conversa;
- número de telefone;
- e-mail;
- suporte no site da empresa;
- visita a uma loja ou agência;
- formulário de suporte.
A transferência na conversa dá a melhor experiência; as outras opções servem de plano B fora do horário.
Bots de IA têm um motivo a mais: os termos da Meta restringem o uso de assistentes de IA de uso geral na plataforma, e um bot de atendimento com escopo fechado e saída para humano fica claramente do lado do uso permitido. Os detalhes estão em política de IA da Meta para chatbots.
Os quatro gatilhos de transferência
| Gatilho | Como detectar | Exemplo |
|---|---|---|
| Pedido explícito | Palavras-chave, botão “Falar com atendente”, ou o LLM classifica a intenção | “quero falar com uma pessoa” |
| Intenção sensível | Lista de assuntos que a empresa decide tratar só com gente | cancelamento, reclamação, cobrança contestada, dados de saúde |
| Falha repetida | Contador de respostas sem sucesso na mesma conversa | o bot não entendeu duas vezes seguidas |
| Cliente prioritário | Consulta ao CRM pelo número do WhatsApp | cliente de contrato corporativo, pedido acima de um valor |
Pedido explícito
Três camadas ajudam:
- Botão sempre à mão. Inclua “Falar com atendente” como opção nas mensagens interativas do bot. Veja mensagens interativas.
- Palavras-chave. “atendente”, “humano”, “pessoa”, “gerente”. Simples, rápido e sem custo de LLM.
- Classificação de intenção. Se o bot usa um LLM, peça que ele marque a intenção
falar_com_humanoquando o cliente pedir com outras palavras.
Intenção sensível
Defina a lista com o time de atendimento e o jurídico, não com o time de tecnologia. Cancelamento, contestação de cobrança, reclamação formal e qualquer conversa com dados sensíveis (saúde, por exemplo) costumam entrar. A LGPD trata dados de saúde como dados sensíveis (art. 5º, II, da Lei 13.709/2018); este artigo não substitui a orientação de um advogado sobre o seu caso.
Falha repetida
Conte as falhas por conversa (“não entendi”, busca vazia, cliente repetindo a pergunta). Duas seguidas é um bom ponto de partida para transferir; zere o contador quando o bot acertar.
Cliente prioritário
O webhook traz o número do cliente em messages[].from. Com ele, o seu sistema consulta o CRM antes de o bot responder. Se o cliente tem um gerente de conta ou um pedido de alto valor em andamento, a conversa pode ir direto para a fila humana, ou o bot faz só a triagem e transfere.
Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →
A máquina de estados da conversa
O ponto central do handoff é um campo de estado por conversa, guardado no banco pelo wa_id do cliente. Todo evento que chega pelo webhook passa por ele antes de qualquer resposta.
gatilho de handoff
┌──────┐ ───────────────────────────▶ ┌────────────────────┐
│ bot │ │ aguardando_humano │
└──────┘ ◀──── timeout sem atendente ── └────────────────────┘
▲ (bot avisa e oferece │
│ outro canal) │ atendente assume
│ ▼
│ ┌──────────────┐
└──────── atendente devolve ──────── │ humano │
ou conversa inativa └──────────────┘| Estado | Quem responde | O bot faz | Sai quando |
|---|---|---|---|
bot | Bot | Responde normalmente | Dispara um gatilho |
aguardando_humano | Ninguém automaticamente | Avisa uma vez e fica em silêncio | Atendente assume, ou estoura o tempo máximo de espera |
humano | Atendente | Nada; só registra as mensagens | Atendente devolve, encerra, ou a conversa fica inativa |
Dois erros comuns:
- Bot respondendo por cima do atendente. Acontece quando o estado fica só na memória do processo ou quando dois workers processam a mesma conversa. Guarde o estado no banco e processe as mensagens de uma conversa em ordem.
- Conversa presa em
humanopara sempre. O cliente volta uma semana depois e ninguém responde, porque o bot acha que tem gente cuidando. Use um tempo de inatividade para devolver ao bot.
O que passar para o atendente
O atendente não deve ler 40 mensagens para entender o caso. Junto com a transferência, entregue um cartão com:
| Item | De onde vem |
|---|---|
| Nome e número | contacts[].profile.name e messages[].from no webhook |
| Motivo da transferência | O gatilho que disparou (pedido, sensível, falha, prioritário) |
| Resumo em 2 ou 3 linhas | Gerado pelo LLM a partir do histórico, ou montado pelas respostas do fluxo |
| Dados já coletados | Número do pedido, CPF parcial, e-mail, produto |
| Origem | Anúncio, site, QR code; o webhook traz o objeto referral quando a conversa começa por anúncio Click-to-WhatsApp |
| Horário da última mensagem do cliente | messages[].timestamp, para saber quanto da janela de 24 horas resta |
| Link para o histórico completo | Seu banco ou CRM |
Um exemplo de payload que o seu sistema pode publicar na fila de atendimento ou no CRM:
{
"conversa_id": "5511988887777",
"motivo": "intencao_sensivel:cancelamento",
"resumo": "Cliente quer cancelar a assinatura anual. Já informou o e-mail e o número do pedido. Perguntou sobre reembolso proporcional.",
"dados": { "pedido": "48213", "email": "cliente@exemplo.com" },
"origem": { "tipo": "ad", "source_id": "120226305854810726" },
"ultima_mensagem_cliente": "2026-10-29T14:02:11-03:00",
"janela_expira_em": "2026-10-30T14:02:11-03:00",
"prioridade": "normal"
}O resumo do LLM pode errar: mostre o histórico completo logo abaixo.
Como avisar o cliente
A mensagem de transição precisa dizer três coisas: que uma pessoa vai assumir, quanto tempo deve levar e o que fazer se for fora do horário.
- Dentro do horário: “Vou chamar uma pessoa do nosso time. O tempo médio de espera agora é de alguns minutos, e você não precisa repetir nada.”
- Fora do horário: “Nosso time atende de segunda a sexta, das 8h às 18h. Deixei seu caso registrado e alguém responde aqui no primeiro horário. Se for urgente, ligue para (11) 0000-0000.”
Mande o aviso uma vez. Se o cliente escrever de novo enquanto espera, o bot não responde a cada mensagem; no máximo, reforça o aviso depois de um intervalo. Mensagens de boas-vindas e de ausência por horário são tratadas em mensagem de boas-vindas e ausência na API.
Atenção à janela de 24 horas
Texto livre só pode ser enviado até 24 horas depois da última mensagem do cliente. Se a fila humana demora e a janela fecha, o atendente não consegue mais responder com texto livre: precisa de um template aprovado para retomar o contato. Por isso o cartão do atendente mostra quando a janela expira, e a fila deve ser ordenada considerando esse prazo. As regras estão em janela de 24 horas do WhatsApp.
Como devolver ao bot
O retorno ao bot pode acontecer de três formas:
- O atendente devolve. Um botão “Devolver ao bot” na ferramenta de atendimento muda o estado para
bot. O bot não deve mandar mensagem nesse momento; ele só volta a responder na próxima mensagem do cliente. - O atendente encerra. Ao fechar o caso, o estado volta para
bote o histórico do atendimento fica registrado para a próxima conversa. - Inatividade. Se a conversa está em
humanoe ninguém escreve por um período definido (por exemplo, algumas horas), o sistema devolve ao bot.
Ao voltar, inclua no contexto do LLM uma nota como “caso tratado pelo atendente em tal data”, para o bot não reabrir o assunto.
SLA: o que medir
Meça o handoff com dados que o seu próprio sistema já registra:
| Métrica | Como calcular |
|---|---|
| Taxa de transferência | Conversas transferidas ÷ conversas atendidas pelo bot |
| Transferências por gatilho | Contagem por motivo (pedido, sensível, falha, prioritário) |
| Tempo até o atendente assumir | Horário em que entrou em humano − horário em que entrou em aguardando_humano |
| Janelas perdidas na fila | Conversas em que a janela de 24 horas fechou antes de o atendente responder |
| Devoluções ao bot | Conversas que voltaram para bot e foram resolvidas sem novo handoff |
Muitas transferências por “falha” indicam que falta conteúdo ao bot; muitas por “pedido explícito” logo na primeira mensagem sugerem que o bot não se apresenta bem. Métricas de atendimento em geral (TMR, TMA, CSAT) estão em métricas de atendimento no WhatsApp.
Pseudocódigo do roteador
O roteador roda para cada mensagem recebida, depois da deduplicação pelo ID wamid.
def rotear(msg, conversa):
conversa.ultima_msg_cliente = msg.timestamp
registrar_no_historico(conversa, msg)
if conversa.estado == "humano":
notificar_atendente(conversa, msg) # o bot fica em silêncio
return
if conversa.estado == "aguardando_humano":
if passou_do_tempo_maximo(conversa):
enviar_texto(msg.from_, AVISO_OUTRO_CANAL)
conversa.estado = "bot"
return # não responde a cada mensagem
# estado == "bot"
motivo = detectar_gatilho(msg, conversa) # pedido, sensível, falha, prioritário
if motivo:
return transferir(conversa, motivo)
resposta = bot_responder(conversa)
if resposta.falhou:
conversa.falhas += 1
if conversa.falhas >= 2:
return transferir(conversa, "falha_repetida")
else:
conversa.falhas = 0
enviar_texto(msg.from_, resposta.texto)
def transferir(conversa, motivo):
conversa.estado = "aguardando_humano"
conversa.entrou_na_fila = agora()
enviar_texto(conversa.wa_id, aviso_de_transferencia(dentro_do_horario()))
publicar_na_fila_humana({
"conversa_id": conversa.wa_id,
"motivo": motivo,
"resumo": resumir(conversa.historico),
"janela_expira_em": conversa.ultima_msg_cliente + horas(24),
})
def atendente_assumiu(conversa, atendente_id):
conversa.estado = "humano"
conversa.atendente = atendente_id
registrar_metrica("tempo_ate_assumir", agora() - conversa.entrou_na_fila)
def devolver_ao_bot(conversa):
conversa.estado = "bot"
conversa.falhas = 0
adicionar_nota_de_contexto(conversa, "atendimento humano concluído")enviar_texto chama a API com o payload padrão da Meta (type: "text"); fila e notificação ficam na sua ferramenta (tickets, CRM, tela própria).
E quando o atendente responde pelo celular?
Com coexistência, o mesmo número fica no app WhatsApp Business e na API. As mensagens que o atendente manda pelo app chegam ao seu sistema como eventos de eco. O roteador pode usar esse eco para mudar a conversa para humano automaticamente: se uma pessoa respondeu pelo celular, o bot sai de cena. O que sincroniza e o que não sincroniza está em coexistência: o que sincroniza.
Como fazer o handoff com a Vectalk
A Vectalk entrega a API oficial: você recebe os webhooks no formato da Meta e envia pelo endpoint POST https://apis.vectalk.com.br/api/messages, com o mesmo payload. O painel da Vectalk não tem caixa de entrada de atendimento nem bot nativo. O roteador, o estado da conversa e a tela do atendente ficam no seu sistema ou na ferramenta que você liga à API (um CRM, uma plataforma de atendimento, um fluxo no n8n).
Na prática, o desenho fica assim:
- Registre a URL do seu roteador como webhook da instância (documentação de webhooks). Você pode registrar mais de uma URL; todas recebem o mesmo evento.
- O roteador decide entre bot e humano e envia as respostas pela API.
- A ferramenta de atendimento lê e responde pelas mesmas chamadas, ou o time usa o app no celular com coexistência.
Se vários atendentes vão usar o mesmo número, veja vários atendentes no mesmo número. Para começar, crie sua conta em apps.vectalk.com.br/register e leia o guia da API oficial do WhatsApp.
Perguntas frequentes
A API do WhatsApp tem um recurso nativo de transferência para humano?
Não. A Cloud API envia e recebe mensagens; quem decide se a resposta vem do bot ou de uma pessoa é o seu sistema. O handoff é uma mudança de estado no seu banco, não uma chamada de API.
O que acontece se ninguém assumir a conversa?
Defina um tempo máximo na fila. Quando ele estoura, o bot avisa o cliente, oferece outro canal (telefone, e-mail, formulário) e registra o caso para retorno. Se a janela de 24 horas fechar, o retorno só pode ser feito com template.
As mensagens do atendente são cobradas como as do bot?
Sim. Para a Meta, uma resposta de texto livre dentro da janela é mensagem de serviço, seja escrita por pessoa ou por IA de terceiros. Desde 1º/10/2026, cada número tem 1.000 mensagens de serviço gratuitas por mês e paga a partir da 1.001ª; para destinatários no Brasil, a tarifa é R$ 0,0350 por mensagem entregue.
Posso deixar o bot sugerindo respostas para o atendente?
Pode. Nesse modelo, o LLM gera um rascunho na tela do atendente, que revisa e envia. É uma forma de manter o humano no controle em assuntos sensíveis sem perder velocidade.
Fontes oficiais consultadas em 29/10/2026: Política de Mensagens do WhatsApp Business (atualizada em 23/09/2026), Termos da Meta para a Plataforma do WhatsApp Business, Janela de atendimento ao cliente, Preços da plataforma, Webhook de mensagens de texto e objeto referral, Webhooks (Vectalk), Lei 13.709/2018 (LGPD).
Coloque o WhatsApp oficial da sua empresa para funcionar
Crie sua conta, conecte seu número à API oficial (dá para manter o app com coexistência) e comece a atender e enviar mensagens.