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

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:

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 e para o envio de arquivos. É 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 — usa a conexão padrão da conta. Se você tem mais de um número, essa é a última que conectou, e não necessariamente a 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ê.

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:

HTTP	Quando
400	Campo faltando, tipo errado, telefone inválido ou mensagem maior que 4096 caracteres
401	Chave de API ausente ou inválida
403	O `session_id` informado não pertence a sua conta
429	Limite de requisições excedido (100/min)
502	Falha no envio — problema de conexão com WhatsApp
503	WhatsApp não conectado. Verifique a conexão no painel.

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 até 100 contatos da sua conta, ordenados pelo mais recente primeiro.

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"
    }
  ]
}

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:

total_contacts — contatos no seu CRM
total_messages — mensagens trocadas (enviadas + recebidas)
active_conversations — contatos com status que não é "perdido" nem "cliente"

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

Faz o mesmo que o botão Pausar Bot do painel: o assistente para de responder aquele contato e a conversa fica só com o atendente humano. A pausa é por tempo indeterminado.

No lugar de :jid você pode usar o número puro ou o JID completo. 5511999999999 e 5511999999999@s.whatsapp.net funcionam igual — sem o sufixo, o servidor completa sozinho.

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 pausa indeterminada: o bot só volta com o /resume ou pelo botão do painel. 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.

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
}

O campo was_paused diz se a conversa estava pausada antes da chamada. Serve para a sua automação saber se a ação teve efeito ou se o bot já estava ativo — útil para não registrar uma retomada que não aconteceu.

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ê 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 — pausa indeterminada não dura para sempre. Se a conversa passar 30 dias sem nenhuma mensagem nova, a limpeza automática remove a pausa junto com a conversa antiga, e o bot volta a responder aquele contato. Se você precisa que um contato nunca receba resposta do assistente, o caminho certo é bloquear o contato, e não pausar a conversa.

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

Faz o mesmo que o botão Encaminhar do painel: 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.

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

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 do CRM, o mesmo que arrastar o cartão no Kanban. O contato precisa já existir no CRM.

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"
}

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". Pelo painel, sai como "manual_panel". 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

const API_KEY = 'sua_chave_aqui';
const BASE = 'https://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'

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

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_id explicitamente 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

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_id explicitamente
Após reconectar, aguarde uns 30 segundos antes de tentar de novo

Recebo 403 ao passar session_id

O session_id passado 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

Próximos passos

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

Falar com Suporte

API Pública do AgeuBot

Base URL e autenticação

1 Gerar sua chave de API

Passo a passo:

Limite de requisições

Endpoints

POST /send — Enviar mensagem

GET /sessions — Listar seus números conectados

GET /contacts — Listar contatos

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

GET /stats — Estatísticas da conta

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

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

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

GET /team — Listar a equipe

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

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

Exemplo completo em Node.js

Exemplo em Python

Boas práticas

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