Recurso em beta: pode mudar. O formato de chat completions foi escrito do conhecimento público (a página oficial recusou o nosso leitor automático); precisa ser conferido com uma chamada real antes de depender dele.
Gatilhos, limites e proteções comuns estão na visão geral dos bots.
Situação: versão beta, em fase de testes.
Para que serve?
Para o caso mais simples e mais comum: um assistente que responde dúvidas seguindo as suas instruções, sem montar fluxos nem plataformas. Você escreve quem ele é, o que sabe e o que não deve fazer; o modelo cuida do resto. É também o tipo mais flexível: troque de serviço mudando o endereço e o modelo.
Quais serviços funcionam?
Qualquer um que aceite POST /chat/completions com o formato da OpenAI:
| Serviço | url base (exemplo) |
Observação |
|---|---|---|
| OpenAI | https://api.openai.com/v1 |
Chave da OpenAI |
| OpenRouter | https://openrouter.ai/api/v1 |
Escolha o modelo pelo nome do catálogo |
| Groq | https://api.groq.com/openai/v1 |
Respostas rápidas; veja os limites da sua conta |
| Ollama | https://ollama.seudominio.com.br/v1 |
Seu servidor; chave opcional; precisa de https público |
Confira o endereço exato na documentação do serviço: eles mudam. Para a Anthropic, use o tipo próprio: Claude.
Como configuro?
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_DO_SERVICO",
"model": "gpt-4o-mini",
"system_prompt": "Você é o atendimento da Loja Exemplo, em Joinville. Responda em português, em até 3 frases, sem markdown. Horário: seg a sex, 9h às 18h. Se não souber, diga que vai chamar um atendente.",
"history_messages": 10,
"max_tokens": 300,
"trigger": "all",
"ignore_groups": true,
"delay_seconds": 2,
"unknown_message": "Por enquanto só entendo texto. Pode escrever sua dúvida?"
}'
| Campo | Para que serve |
|---|---|
url |
Endereço base do serviço (a ProxyBox acrescenta /chat/completions) |
api_key |
Chave do serviço; cifrada; opcional se o endereço for seu |
model |
Nome do modelo |
system_prompt |
Instruções fixas do assistente |
history_messages |
Quantas mensagens anteriores o modelo vê (0 a 20; padrão 10) |
max_tokens |
Tamanho máximo da resposta |
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisO que a ProxyBox envia?
{
"model": "gpt-4o-mini",
"max_tokens": 300,
"messages": [
{ "role": "system", "content": "Você é o atendimento da Loja Exemplo..." },
{ "role": "user", "content": "Vocês abrem sábado?" },
{ "role": "assistant", "content": "Abrimos de segunda a sexta, das 9h às 18h." },
{ "role": "user", "content": "E feriado?" }
]
}
As mensagens anteriores vêm da memória curta que a ProxyBox guarda por contato (cifrada, até history_messages). A resposta usada é choices[0].message.content.
Exceção de rede para OpenAI e Anthropic
A guarda de rede da ProxyBox só fala com endereços públicos, https, sem seguir redirecionamentos. Os domínios api.openai.com e api.anthropic.com têm uma exceção técnica (https puro, sem porta). Para os demais serviços, vale a regra geral: https, nome que resolve para IP público, porta 443 ou 8443.
Como escrevo boas instruções?
O resultado depende mais disso do que do modelo.
- Diga quem é e para quem: "Você atende clientes da Loja Exemplo pelo WhatsApp."
- Dê os fatos que ele deve usar: horário, endereço, prazos, formas de pagamento.
- Diga o que ele não deve fazer: não prometer prazo diferente do informado, não dar desconto, não falar de preço que não está nas instruções.
- Peça formato curto e sem markdown: o WhatsApp não renderiza títulos nem tabelas.
- Diga o plano B: "Se não souber, responda 'vou chamar um atendente'" e use
finish_keywordsou a pausa do dono para assumir.
Modelos erram com confiança. Para uma fase de teste segura, ligue a aprovação humana em bots: você lê cada resposta antes de sair.
Quais limites e custos devo ter em mente?
- Você paga o serviço de IA conforme o plano dele. O limite da ProxyBox de 20 respostas por hora por conversa e 200 por dia também ajuda a limitar o gasto.
- 15 segundos de tempo limite por chamada; modelos lentos podem estourar.
- Resposta de até 1 MB.
- O bot só lê texto. Áudio e imagem sem legenda não são enviados ao modelo; use
unknown_message. - Os dados da conversa vão para o serviço de IA que você escolheu. Conte isso na sua política de privacidade e escolha o serviço de acordo com a LGPD.
Quais erros aparecem?
| Sintoma | Causa provável |
|---|---|
Estado error: "O bot recusou a mensagem" |
Chave errada, modelo inexistente ou limite da conta do serviço |
| Resposta cortada | max_tokens baixo demais |
| Respostas longas e com markdown | Instruções não pedem formato curto |
| Nada acontece | Gatilho, grupo ignorado ou bot desligado após 10 falhas |
O que está não confirmado?
O formato de chat completions é estável e copiado por vários serviços, mas não foi conferido com uma chamada real nesta rodada. Serviços compatíveis podem ter pequenas diferenças (por exemplo, nomes de modelo e campos opcionais). Se algo falhar, use POST /integrations/bot/test para ver a mensagem de erro curta e ajuste.
Veja também
- Bots de WhatsApp pela API: tipos e limites
- Bot de WhatsApp com Claude (Anthropic)
- Aprovação humana de mensagens da API de WhatsApp
- Segurança da API de WhatsApp: chave e IPs
Índice completo: índice dos guias. Sobre o produto: a API de WhatsApp com IP de provedor.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra as notas técnicas do adaptador openai. Recurso em beta.