Recurso em beta: pode mudar. Cada guia de tipo lista o que está não confirmado.
Para que serve?
Para atender o básico sem gente: horário, endereço, status do pedido, qualificar um contato antes de passar para uma pessoa. A parte inteligente fica no bot que você já usa (um fluxo do Typebot, um agente do Dify, uma resposta de IA); a ProxyBox cuida da conversa com o WhatsApp: ler a mensagem, chamar o bot, enviar a resposta com pausa, respeitar os limites.
Quais tipos existem?
| Tipo | O que é | Guia |
|---|---|---|
typebot |
Fluxo visual de conversa | Typebot |
dify |
Aplicativo de chat do Dify | Dify |
flowise |
Fluxo do Flowise (prediction) | Flowise |
openai |
Qualquer serviço com chat completions (OpenAI, OpenRouter, Groq, Ollama...) | OpenAI e compatíveis |
anthropic |
Claude, pela API de mensagens da Anthropic | Claude |
n8n e webhook |
Seu fluxo ou seu servidor, por um POST assinado | n8n e webhook |
Como ligo um bot?
Pelo painel (aba Bot) ou pela API:
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{
"type": "openai",
"enabled": true,
"url": "https://api.openai.com/v1",
"api_key": "SUA_CHAVE_DA_OPENAI",
"model": "gpt-4o-mini",
"system_prompt": "Você atende a loja Exemplo. Seja breve e educado.",
"trigger": "all",
"ignore_groups": true,
"stop_on_human_minutes": 30,
"delay_seconds": 2
}'
Sem "enabled": true o bot é gravado, mas fica desligado. As rotas do bot, todas com a chave da instância: GET / PUT / DELETE /integrations/bot, POST /integrations/bot/test, GET /integrations/bot/sessions e POST /integrations/bot/sessions/{chat}/reset ou /pause. As respostas nunca devolvem segredos inteiros: aparecem como •••• e os 4 últimos caracteres.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisQuais ajustes valem para todos os tipos?
| Ajuste | Padrão | Efeito |
|---|---|---|
trigger |
all |
all responde sempre; keyword só começa quando a mensagem tem uma das keywords; first_message começa na primeira mensagem do chat (ou depois de expire_minutes) |
keywords |
vazio | Palavras que iniciam a conversa (sem diferenciar acento e maiúscula); uma conversa ativa continua |
finish_keywords |
vazio | Se a mensagem inteira for uma delas, a sessão fecha sem resposta |
ignore_groups |
true |
Grupos não chamam o bot |
ignore_jids |
vazio | Números ou conversas que o bot nunca atende |
expire_minutes |
30 | Depois desse tempo sem mensagens, a sessão acaba |
delay_seconds |
0 | De 0 a 10: mostra "digitando…", espera e envia |
unknown_message |
vazio | Resposta para o que o bot não entende (áudio, figurinha, imagem sem legenda) |
stop_on_human_minutes |
30 | Se você responde pelo celular, o bot pausa nessa conversa (0 desliga) |
debounce |
false |
Junta mensagens coladas; usa o agrupamento quando buffer_seconds está ligado |
history_messages |
10 | De 0 a 20: quantas mensagens anteriores o bot lembra (OpenAI, Claude, n8n, webhook) |
max_tokens |
do tipo | Tamanho máximo da resposta gerada (OpenAI e Claude) |
Como o bot decide quando responder?
Em ordem: a mensagem é ignorada se foi enviada por você, se vem de status ou canal, se é do próprio número, se está na lista de ignorados ou se é de grupo (com ignore_groups ligado). Depois vem o gatilho. Se passar, o bot é chamado uma vez por turno. Mensagens que chegam enquanto o bot responde esperam e viram o próximo turno (no máximo 3 turnos por execução). A mesma mensagem nunca é respondida duas vezes (a deduplicação guarda o id por 24 horas).
Que proteções existem?
- Limites: no máximo 20 respostas por hora em cada conversa e 200 por dia na instância.
- Corte de loop: se o bot repete a última resposta, ou responde 6 vezes em 60 segundos na mesma conversa, a conversa é pausada por 30 minutos, com aviso no estado do bot.
- Pausa quando você responde: o aviso
message.sentde uma mensagem que não é do bot dispara a pausa. - Texto longo: a resposta é dividida em partes de até 1.500 caracteres, com pausa de 1 segundo entre elas, até 10 mensagens por turno.
- Travas da API: a resposta sai pela operação de envio normal. Se o telefone está em não perturbe, se há trava de contato novo ou limite de ritmo, o bot para na hora, sem repetir.
- Aprovação: com o modo
bots, a resposta espera um humano. - Segredos: chaves do bot ficam cifradas e nunca aparecem em log, resposta ou erro.
- Rede: o bot só fala com endereços https públicos (a guarda de rede da ProxyBox bloqueia endereços internos), sem seguir redirecionamentos, com tempo limite de 15 segundos e resposta de até 1 MB.
O que acontece quando o bot dá erro?
O estado vira error com uma frase curta em português (nunca o corpo da resposta do serviço nem a chave). A ProxyBox tenta de novo com espera crescente (15 segundos, 30 segundos, até 1 hora) e desliga o bot sozinha na 10ª falha seguida, com aviso destacado. Salvar a configuração de novo zera o contador.
Como testo sem enviar?
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/test" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"text": "Qual o horário de vocês?"}'
A resposta mostra o que o bot devolveria e deixa claro que nada foi enviado ao WhatsApp. Limite de 10 testes por minuto.
Como vejo as conversas ativas?
GET /integrations/bot/sessions lista as sessões (chat, se está ativa ou pausada até quando, última mensagem, respostas na hora). Para limpar uma conversa, POST /integrations/bot/sessions/5547999999999/reset; para pausar por 60 minutos, POST .../pause com {"minutes": 60}; com 0 o bot volta a responder.
O que o bot não faz?
- Não ouve áudio nem vê imagem. Sem transcrição e sem leitura de imagem.
- Não substitui um atendente. Use
finish_keywordse a pausa automática para passar a conversa a uma pessoa, e o Chatwoot para organizar o atendimento. - Não evita bloqueio. Respostas automáticas em volume são um sinal que o WhatsApp observa; por isso existem os tetos de 20 por hora e 200 por dia.
- Sem garantias de conteúdo. O que um modelo de IA responde é de responsabilidade de quem configura o bot. Teste, use instruções claras e, se possível, a aprovação humana.
Veja também
- Typebot no WhatsApp: ligar um fluxo à API
- Bot de IA no WhatsApp com OpenAI, Groq, Ollama
- Aprovação humana de mensagens da API de WhatsApp
- Chatwoot com WhatsApp: ligar pela API
Índice completo: documentação. Sobre o produto: API de WhatsApp por instância.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra as notas técnicas dos bots da versão 1.2. Recurso em beta.