Central de Ajuda

API Pública do AgeuBot

Envie mensagens pelo WhatsApp, liste contatos e consulte estatísticas via HTTP. Integre o AgeuBot com qualquer sistema que fale HTTP.

Use a API Pública para conectar o AgeuBot ao seu sistema. Dispare mensagens a partir de um CRM próprio, notifique clientes de um ERP, liste contatos em um dashboard — tudo com uma chave de API simples.

Base URL e autenticação

Todos os endpoints da API Pública estão sob o prefixo:

https://ageubot.com.br/api/public

O painel abre para você em i2.ageubot.com.br? Então a sua conta está na instância 2: use https://i2.ageubot.com.br/api/public em todas as chamadas, no lugar do endereço acima. A chave de API só vale no endereço da sua conta; em ageubot.com.br ela responde 401. No painel, em Integrações › Documentação API, o endereço certo já aparece para você. Os exemplos desta página usam ageubot.com.br.

A autenticação é feita pelo cabeçalho x-api-key em toda requisição:

x-api-key: sua_chave_de_api_aqui

1 Gerar sua chave de API

Passo a passo:

  1. No painel do AgeuBot, va em Integrações
  2. Clique em API
  3. Clique em "Gerar Nova Chave"
  4. Copie a chave gerada e guarde em local seguro

Atenção: Trate sua chave de API como senha. Quem tiver ela pode enviar mensagens pelo seu WhatsApp conectado e ver seus contatos. Nunca coloque a chave em código publicado em repositórios, apps mobile ou HTML de site.

Limite de requisições

A API Pública aceita até 100 requisições por minuto por chave, somando todas as rotas. Quando o limite é atingido, a API responde com HTTP 429 e você deve esperar antes de tentar novamente.

Além disso, os envios têm um limite próprio de 15 mensagens por minuto por conta. Vale para POST /send, POST /send-file e POST /send-template e conta também os áudios e arquivos que a sua equipe manda pelo painel; tentativas que voltam com erro também contam. É uma proteção contra bloqueio do número pelo WhatsApp. Se o seu CRM dispara em rajada, espace os envios: 16 numa mesma janela de um minuto já devolve 429, mesmo você estando longe das 100 requisições.

Endpoints

POST /send — Enviar mensagem

Envia uma mensagem de texto pelo WhatsApp para o número informado.

Corpo da requisição (JSON):

CampoTipoObrigatórioDescrição
phonestringsimNúmero completo com DDI + DDD (10 a 15 dígitos). Ex: 5511999999999
messagestringsimTexto da mensagem. Máximo 4096 caracteres.
session_idstringnãoPor qual dos seus números a mensagem deve sair. Três formas:
omitir: se a conta tem um número só, a mensagem sai por ele. Com dois ou mais, informe sempre o session_id (ou "auto"): sem ele a mensagem pode sair por um número que não é o da conversa.
um ID: envia por aquele número. Pegue os IDs em GET /sessions. Só aceita sessões da própria conta.
"auto": envia pelo mesmo número em que a conversa com esse contato está acontecendo. Se ainda não houve conversa, a API responde 400 com a lista dos seus números em vez de escolher por você.
Se o número escolhido estiver desconectado, a API responde 503 com a lista dos seus números e não envia por outro.
pause_automationbooleannãotrue pausa o atendimento automático (robô e IA) daquele contato no próprio envio, seguindo a Pausa Automática da sua conta (Automação › Pausa Automática).

Exemplo com curl:

curl -X POST https://ageubot.com.br/api/public/send \ -H "x-api-key: SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{ "phone": "5511999999999", "message": "Ola! Esta e uma mensagem de teste." }'

Resposta 200 — sucesso:

{ "success": true, "message_id": "3EB0A97C11783ED74F44DD" }

Respostas de erro possíveis:

HTTPQuando
400Campo faltando, tipo errado, telefone inválido, mensagem maior que 4096 caracteres, ou a API não conseguiu escolher o número sozinha (a resposta traz a lista dos seus números)
401Chave de API ausente ou inválida
403O session_id informado não pertence a sua conta
429Limite excedido: 100 requisições por minuto por chave, ou 15 envios por minuto por conta
502O WhatsApp não aceitou o envio. Confira a conexão do número antes de repetir: se o erro foi por tempo esgotado, a mensagem pode ter saído.
503WhatsApp não conectado, ou o número escolhido no session_id está desconectado (a resposta traz a lista dos seus números). Nada foi enviado.

POST /send-template: enviar modelo aprovado (API Oficial)

Envia um modelo de mensagem aprovado pela Meta por um número conectado pela API Oficial do WhatsApp. Use quando a pessoa não falou com você nas últimas 24 horas: fora dessa janela, a Meta só entrega modelo aprovado, e o texto livre do POST /send volta como "não entregue" (código 131047).

Corpo da requisição (JSON):

CampoTipoObrigatórioDescrição
phonestringsimNúmero completo com DDI + DDD (10 a 15 dígitos). Ex: 5511999999999
template_namestringsimNome do modelo aprovado, igual ao da Meta: letras minúsculas, números e _. Ex: lembrete_consulta
languagestringnãoIdioma do modelo. Se não vier, usa pt_BR.
paramslista de textosnãoValores das variáveis do corpo do modelo, na ordem: o primeiro preenche {{1}}, o segundo {{2}} e assim por diante (até 30). Mande a mesma quantidade de variáveis que o modelo tem.
session_idstringnãoPor qual número da API Oficial o modelo sai (pegue o ID em GET /sessions). Sem ele, sai pela primeira conexão da API Oficial da conta; se você tem mais de uma, informe sempre. Número conectado por QR Code não envia modelo.

Variáveis: a Meta não aceita quebra de linha, tabulação nem mais de quatro espaços seguidos dentro de uma variável. O AgeuBot ajusta antes de enviar: cada quebra de linha vira " | ", tabulação vira espaço, os espaços a mais saem e variável vazia vira "-". Cada variável vai até 1024 caracteres. Em params, a resposta mostra o texto como foi enviado.

Se o modelo tem imagem, vídeo ou documento no cabeçalho, o AgeuBot manda junto o arquivo do próprio modelo. Não precisa enviar nada a mais. O envio aparece na conversa do contato no painel, com o status de entrega.

Exemplo com curl:

curl -X POST https://ageubot.com.br/api/public/send-template \ -H "x-api-key: SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{ "phone": "5511999999999", "template_name": "lembrete_consulta", "language": "pt_BR", "params": ["Maria", "12/11", "14h"] }'

Resposta 200: a Meta aceitou o envio

{ "success": true, "message_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjAwQUE", "session_id": "8d3f1a2b-0c4e-4f6a-9b7d-5e2c1a0f9e88", "contact_jid": "5511999999999@s.whatsapp.net", "params": ["Maria", "12/11", "14h"] }

O 200 quer dizer que a Meta aceitou. Se depois ela não conseguir entregar, a conversa no painel mostra "não entregue" com o motivo.

Respostas de erro possíveis:

HTTPQuando
400Campo faltando ou inválido, session_id que não é da API Oficial, conta sem conexão da API Oficial, ou a Meta recusou o envio. A resposta traz o motivo da Meta. Os mais comuns: quantidade de variáveis diferente da do modelo, nome ou idioma que não batem com o modelo aprovado, ou modelo ainda não aprovado.
401Chave de API ausente ou inválida
403O session_id informado não pertence a sua conta
429Limite excedido: 100 requisições por minuto por chave, ou 15 envios por minuto por conta
503Envio de modelo indisponível naquele momento. Nada foi enviado; tente de novo.

No fluxo: dá para chamar esta rota pelo bloco Requisição HTTP, com o cabeçalho x-api-key e as variáveis do contato em params, por exemplo "params": ["{{nome}}", "{{telefone}}"]. Serve para avisar um consultor no fim do atendimento, mesmo fora das 24 horas.

GET /sessions — Listar seus números conectados

Devolve os números de WhatsApp da sua conta com o session_id de cada um. É esse ID que você usa no campo session_id do envio para escolher por qual número a mensagem sai.

curl https://ageubot.com.br/api/public/sessions \ -H "x-api-key: SUA_CHAVE"

Resposta 200:

{ "sessions": [ { "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "numero": "5511999990001", "nome": "Atendimento", "status": "connected", "slot_number": 1 }, { "session_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "numero": "5511999990002", "nome": "Vendas", "status": "connected", "slot_number": 2 } ] }

Só aparecem conexões de WhatsApp — Instagram e Messenger ficam de fora, porque o envio por essas rotas funciona de outro jeito.

GET /contacts — Listar contatos

Retorna os contatos da sua conta, ordenados pelo mais recente primeiro. Sem parâmetros vêm os 100 mais recentes. Para percorrer a lista inteira ou filtrar, use os parâmetros abaixo na URL.

ParâmetroPara que serve
limitQuantos contatos por chamada. Padrão 100, máximo 500.
pageNúmero da página, começando em 1.
offsetQuantos contatos pular. Use no lugar de page, se preferir.
statusSó os contatos de uma etapa. Aceita a chave (qualificado) ou o nome da etapa.
curl https://ageubot.com.br/api/public/contacts \ -H "x-api-key: SUA_CHAVE"

Resposta 200:

{ "contacts": [ { "jid": "5511999999999@s.whatsapp.net", "name": "Joao Silva", "phone": "5511999999999", "status": "novo", "created_at": "2026-04-22T14:00:00.000Z", "status_label": "Novo" } ], "total": 779, "limit": 100, "offset": 0, "has_more": true }

O campo status é a chave fixa da etapa e status_label é o nome que aparece no seu painel. Se você renomeou a etapa Novo para Sem classificação, o contato vem com "status": "novo" e "status_label": "Sem classificação". Enquanto has_more vier true, peça a página seguinte.

curl "https://ageubot.com.br/api/public/contacts?limit=200&page=2" \ -H "x-api-key: SUA_CHAVE"

GET /statuses: listar as etapas do CRM

Retorna as etapas (colunas do Kanban) da sua conta, na ordem do painel, com a chave, o nome, a cor e quantos contatos há em cada uma. Use para montar a correspondência entre a chave que a API devolve e o nome que você vê no painel.

curl https://ageubot.com.br/api/public/statuses \ -H "x-api-key: SUA_CHAVE"

Resposta 200:

{ "statuses": [ { "status": "novo", "label": "Sem classificação", "color": "#FFD600", "order": 0, "contacts": 416 }, { "status": "qualificado", "label": "Em atendimento", "color": "#2196F3", "order": 1, "contacts": 171 } ] }

GET /messages/:jid — Listar mensagens de um contato

Retorna as últimas 50 mensagens trocadas com o contato informado. Substitua :jid pelo JID completo (URL-encoded).

curl "https://ageubot.com.br/api/public/messages/5511999999999%40s.whatsapp.net" \ -H "x-api-key: SUA_CHAVE"

Resposta 200:

{ "messages": [ { "id": "uuid...", "contact_jid": "5511999999999@s.whatsapp.net", "contact_name": "Joao Silva", "content": "Ola, tudo bem?", "media_type": null, "media_url": null, "is_from_me": 0, "is_read": 1, "timestamp": "2026-04-22T14:00:00.000Z", "whatsapp_msg_id": "3EB0...", "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] }

O campo session_id diz por qual dos seus números aquela mensagem passou. É o que permite responder pelo mesmo número em que a conversa está acontecendo — ou use "session_id": "auto" no envio e deixe a API resolver.

GET /stats — Estatísticas da conta

Retorna contadores básicos da sua conta.

curl https://ageubot.com.br/api/public/stats \ -H "x-api-key: SUA_CHAVE"

Resposta 200:

{ "total_contacts": 1543, "total_messages": 28471, "active_conversations": 1287 }

Onde:

POST /chats/:jid/pause — Pausar o bot

O robô e a IA param de responder só aquele contato, e a conversa fica com o atendente humano; o atendimento automático segue normal para todos os outros. Exemplo com CRM: quando o vendedor assume a conversa, chame o /pause; quando ele terminar, chame o /resume.

A pausa feita pela API fica até o /resume. Ela não vira temporária quando o atendente responde, qualquer que seja a sua Pausa Automática, e enquanto ela vale nem o bloco Colaborador do fluxo nem a mensagem de fora do horário falam com o contato. No painel, Retomar Bot, Reiniciar e Excluir conversa também tiram a pausa.

Uma exceção: se a sua Pausa Automática é por tempo definido e o /pause chega enquanto o robô ainda está mandando a resposta de um fluxo, o fim desse fluxo pode deixar a pausa com prazo. Se isso importa para você, confira o /pause-status alguns segundos depois e, se vier uma data em paused_until, chame o /pause de novo.

No lugar de :jid use o identificador do contato exatamente como vem no /contacts ou nos webhooks (ex.: 5511999999999@s.whatsapp.net). Só os dígitos também funcionam (o servidor completa com @s.whatsapp.net), mas, se o contato estiver guardado de outro jeito (por exemplo, sem o nono dígito), a pausa fica num identificador que não recebe mensagem e o robô continua respondendo. Para Instagram e Messenger, use sempre o identificador completo.

Não tem corpo. Toda a informação vai na URL.

curl -X POST https://ageubot.com.br/api/public/chats/5511999999999/pause \ -H "x-api-key: SUA_CHAVE"

Resposta 200 — sucesso:

{ "success": true, "jid": "5511999999999@s.whatsapp.net", "is_paused": true, "paused_until": null }

paused_until: null significa que a pausa fica até o /resume (veja acima o que mais a tira). Chamar duas vezes não duplica nada, apenas atualiza o horário da pausa.

POST /chats/:jid/resume — Retomar o bot

Equivale ao botão Retomar Bot do painel: remove a pausa e devolve a conversa ao assistente. Se a conversa estava finalizada (botão Finalizar ou encerrada pela automação), ela também é reaberta.

curl -X POST https://ageubot.com.br/api/public/chats/5511999999999/resume \ -H "x-api-key: SUA_CHAVE"

Resposta 200 — sucesso:

{ "success": true, "jid": "5511999999999@s.whatsapp.net", "was_paused": true, "is_paused": false, "reopened": false }

O campo was_paused diz se havia uma pausa valendo antes da chamada (uma pausa temporária que já tinha vencido não conta). Serve para a sua automação saber se a ação teve efeito ou se o bot já estava ativo, e não registrar uma retomada que não aconteceu. O campo reopened diz se a conversa finalizada foi reaberta.

GET /chats/:jid/pause-status — Consultar o estado

Consulta se o bot está pausado naquela conversa, sem alterar nada.

curl https://ageubot.com.br/api/public/chats/5511999999999/pause-status \ -H "x-api-key: SUA_CHAVE"

Resposta 200:

{ "jid": "5511999999999@s.whatsapp.net", "is_paused": false, "paused_until": null }
O que você recebeO que significa
is_paused: falseO bot está ativo nessa conversa
is_paused: true com paused_until: nullPausa por tempo indeterminado
is_paused: true com uma dataPausa temporária: o bot volta sozinho naquele horário

Respostas de erro das três rotas:

HTTPQuando
400JID vazio na URL
401Chave de API ausente ou inválida
429Limite de requisições excedido (100/min)

Atenção: a pausa sai junto com a conversa antiga. Quando a limpeza automática apaga uma conversa sem mensagens novas (depois de 60 dias em conta assinante; 30 nas demais), a pausa vai junto, e o atendimento automático volta para aquele contato. Isso vale para qualquer pausa, inclusive a do botão Finalizar do painel. Para manter um contato sem resposta automática por mais tempo, chame o /pause de novo de tempos em tempos (uma vez por semana basta): cada chamada renova a pausa.

GET /team — Listar a equipe

Devolve os atendentes cadastrados na conta. Serve para montar o de para entre os responsáveis do seu sistema e as pessoas do AgeuBot, sem precisar digitar os identificadores na mão.

curl https://ageubot.com.br/api/public/team \ -H "x-api-key: SUA_CHAVE"

Resposta 200:

{ "success": true, "total": 2, "members": [ { "id": "a1b2c3d4-...", "name": "Sofia Martins", "email": "sofia@suaempresa.com.br", "phone": "5511999999999", "role": "atendente", "is_active": 1 } ] }

POST /chats/:jid/assign — Encaminhar a conversa

Marca a conversa como atribuída ao atendente, avisa ele no painel e, se a notificação por WhatsApp estiver ligada no cadastro dele, manda a mensagem também. Diferente do botão Encaminhar do painel, não confere se o atendente atende o número daquela conversa nem se ele está ativo: confira o campo is_active no GET /team antes de encaminhar.

Você identifica o atendente de duas formas, à sua escolha:

CorpoQuando usar
{"member_id": "a1b2c3d4-..."}Quando você já guardou o identificador da rota /team
{"email": "sofia@suaempresa.com.br"}Quando o seu sistema já conhece o e mail do responsável — dispensa manter uma tabela de para do seu lado
curl -X POST https://ageubot.com.br/api/public/chats/5511999999999/assign \ -H "x-api-key: SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{"email": "sofia@suaempresa.com.br"}'

Resposta 200:

{ "success": true, "jid": "5511999999999@s.whatsapp.net", "assigned_to": { "id": "a1b2c3d4-...", "name": "Sofia Martins", "email": "sofia@suaempresa.com.br" } }

PUT /contacts/:jid/status — Mudar o status do CRM

Move o contato para outra etapa (coluna do Kanban) do CRM. O contato precisa já existir no CRM. No status você pode mandar a chave da etapa (novo, qualificado etc.) ou o nome dela como aparece no painel. A chave nasce do nome com que a etapa foi criada e não muda quando você a renomeia (uma etapa criada como Em Negociação fica em_negociacao mesmo depois de renomeada). A lista de chaves e nomes da sua conta está no GET /statuses. A resposta e o webhook trazem sempre a chave em new_status e o nome em new_status_label. Um valor que não é etapa sua também é gravado, sem erro, e o cartão aparece em Novo.

curl -X PUT https://ageubot.com.br/api/public/contacts/5511999999999/status \ -H "x-api-key: SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{"status": "qualificado"}'

Resposta 200:

{ "success": true, "jid": "5511999999999@s.whatsapp.net", "contact_id": "e5f6...", "old_status": "novo", "new_status": "qualificado", "old_status_label": "Novo", "new_status_label": "Qualificado" }

O campo old_status diz de onde o contato saiu. Guarde o antes de aplicar um status temporário e você consegue devolver o contato exatamente para a etapa em que ele estava.

Como não reagir ao próprio eco. Quando o status muda por esta rota, o webhook status_changed sai com "source": "public_api"; mudanças feitas no painel nunca trazem esse valor. Se a sua automação escuta esse webhook e também escreve status, use esse campo para distinguir — sem ele, a automação reage à própria alteração e entra em laço.

Respostas de erro das três rotas:

HTTPQuando
400Faltou member_id ou email no encaminhamento, ou status vazio
401Chave de API ausente ou inválida
404Atendente não encontrado nesta conta, ou contato que não está no CRM
429Limite de requisições excedido (100/min)

Exemplo completo em Node.js

const API_KEY = 'sua_chave_aqui'; const BASE = 'https://ageubot.com.br/api/public'; // conta na instância 2: 'https://i2.ageubot.com.br/api/public' async function enviar(phone, message) { const resp = await fetch(`${BASE}/send`, { method: 'POST', headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ phone, message }) }); const data = await resp.json(); if (!resp.ok) throw new Error(data.error || 'Falha'); return data.message_id; } enviar('5511999999999', 'Ola do meu sistema!') .then(id => console.log('Enviada:', id)) .catch(err => console.error('Erro:', err.message));

Exemplo em Python

import requests API_KEY = 'sua_chave_aqui' BASE = 'https://ageubot.com.br/api/public' # conta na instância 2: 'https://i2.ageubot.com.br/api/public' def enviar(phone, message): r = requests.post( f'{BASE}/send', headers={'x-api-key': API_KEY}, json={'phone': phone, 'message': message} ) r.raise_for_status() return r.json()['message_id'] msg_id = enviar('5511999999999', 'Ola do Python!') print('Enviada:', msg_id)

Boas práticas

Dica: Para receber eventos em tempo real (mensagens recebidas, contatos criados, etc.), configure webhooks em vez de ficar fazendo polling. Veja Configurar Webhooks.

Problemas comuns

Recebo 401 mesmo com a chave correta

Recebo 503 "WhatsApp não conectado"

Recebo 403 ao passar session_id

Mensagem não chega ao destinatário

Próximos passos


Precisa de ajuda com a integração? Fale com nosso suporte pelo WhatsApp.

Falar com Suporte