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:
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:
1 Gerar sua chave de API
Passo a passo:
- No painel do AgeuBot, va em Integrações
- Clique em API
- Clique em "Gerar Nova Chave"
- 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):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
phone | string | sim | Número completo com DDI + DDD (10 a 15 dígitos). Ex: 5511999999999 |
message | string | sim | Texto da mensagem. Máximo 4096 caracteres. |
session_id | string | não | Por 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_automation | boolean | não | true 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:
Resposta 200 — sucesso:
Respostas de erro possíveis:
| HTTP | Quando |
|---|---|
| 400 | Campo 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) |
| 401 | Chave de API ausente ou inválida |
| 403 | O session_id informado não pertence a sua conta |
| 429 | Limite excedido: 100 requisições por minuto por chave, ou 15 envios por minuto por conta |
| 502 | O 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. |
| 503 | WhatsApp 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):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
phone | string | sim | Número completo com DDI + DDD (10 a 15 dígitos). Ex: 5511999999999 |
template_name | string | sim | Nome do modelo aprovado, igual ao da Meta: letras minúsculas, números e _. Ex: lembrete_consulta |
language | string | não | Idioma do modelo. Se não vier, usa pt_BR. |
params | lista de textos | não | Valores 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_id | string | não | Por 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:
Resposta 200: a Meta aceitou o envio
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:
| HTTP | Quando |
|---|---|
| 400 | Campo 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. |
| 401 | Chave de API ausente ou inválida |
| 403 | O session_id informado não pertence a sua conta |
| 429 | Limite excedido: 100 requisições por minuto por chave, ou 15 envios por minuto por conta |
| 503 | Envio 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.
Resposta 200:
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âmetro | Para que serve |
|---|---|
limit | Quantos contatos por chamada. Padrão 100, máximo 500. |
page | Número da página, começando em 1. |
offset | Quantos contatos pular. Use no lugar de page, se preferir. |
status | Só os contatos de uma etapa. Aceita a chave (qualificado) ou o nome da etapa. |
Resposta 200:
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.
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.
Resposta 200:
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).
Resposta 200:
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.
Resposta 200:
Onde:
total_contacts— contatos no seu CRMtotal_messages— mensagens trocadas (enviadas + recebidas)active_conversations— contatos com status que não é "perdido" nem "cliente"
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.
Resposta 200 — sucesso:
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.
Resposta 200 — sucesso:
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.
Resposta 200:
| O que você recebe | O que significa |
|---|---|
is_paused: false | O bot está ativo nessa conversa |
is_paused: true com paused_until: null | Pausa por tempo indeterminado |
is_paused: true com uma data | Pausa temporária: o bot volta sozinho naquele horário |
Respostas de erro das três rotas:
| HTTP | Quando |
|---|---|
| 400 | JID vazio na URL |
| 401 | Chave de API ausente ou inválida |
| 429 | Limite 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.
Resposta 200:
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:
| Corpo | Quando 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 |
Resposta 200:
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.
Resposta 200:
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:
| HTTP | Quando |
|---|---|
| 400 | Faltou member_id ou email no encaminhamento, ou status vazio |
| 401 | Chave de API ausente ou inválida |
| 404 | Atendente não encontrado nesta conta, ou contato que não está no CRM |
| 429 | Limite de requisições excedido (100/min) |
Exemplo completo em Node.js
Exemplo em Python
Boas práticas
- Nunca exponha sua chave no frontend — sempre chame a API a partir do seu servidor, nunca do navegador ou app mobile
- Trate o 429 — implemente um backoff exponencial quando receber limite de requisições
- Valide o telefone antes de enviar — inclua DDI + DDD para evitar erros
- Monitore o 503 — se chegar muito, algo está derrubando o WhatsApp. Veja WhatsApp desconectou
- Se você tem várias sessões WhatsApp, use
session_idexplicitamente para garantir que a mensagem sai pelo número certo
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
- Confirme que o cabeçalho é
x-api-key(tudo minúsculo, com hífen) - Verifique se a chave foi copiada sem espaços extras no início ou fim
- Confirme no painel que a chave ainda está ativa
- Se o painel abre para você em i2.ageubot.com.br, chame
https://i2.ageubot.com.br/api/public: a chave só vale no endereço da sua conta
Recebo 503 "WhatsApp não conectado"
- Abra o painel do AgeuBot e confirme que o WhatsApp está com status "Conectado"
- Se você tem mais de uma sessão, tente passar
session_idexplicitamente - Se você passou
session_id(ou"auto"), aquele número está desconectado: a resposta traz a lista dos seus números; reconecte ou use outro - Após reconectar, aguarde uns 30 segundos antes de tentar de novo
Recebo 403 ao passar session_id
- O
session_idpassado não pertence a sua conta. Liste suas sessões no painel e use um ID válido
Mensagem não chega ao destinatário
- Confirme que o número tem WhatsApp ativo
- Verifique se o número está no formato completo (DDI + DDD + número, só dígitos)
- O destinatário pode ter bloqueado o seu número
- Número conectado pela API Oficial: se a pessoa não falou com você nas últimas 24 horas, o texto livre do
POST /sendvolta como "não entregue" (código 131047). Nesse caso, envie um modelo aprovado peloPOST /send-template
Próximos passos
- Configurar Webhooks para receber eventos em tempo real
- Conectar seu WhatsApp ao AgeuBot
- O que fazer quando o WhatsApp desconecta
Precisa de ajuda com a integração? Fale com nosso suporte pelo WhatsApp.
Falar com Suporte