API Publica do AgeuBot | Central de Ajuda

Use a API Publica para conectar o AgeuBot ao seu sistema. Dispare mensagens a partir de um CRM proprio, notifique clientes de um ERP, liste contatos em um dashboard — tudo com uma chave de API simples.

Base URL e autenticacao

Todos os endpoints da API Publica estao sob o prefixo:

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

A autenticacao e feita pelo cabecalho x-api-key em toda requisicao:

x-api-key: sua_chave_de_api_aqui

1 Gerar sua chave de API

Passo a passo:

No painel do AgeuBot, va em Integracoes
Clique em API
Clique em "Gerar Nova Chave"
Copie a chave gerada e guarde em local seguro

Atencao: 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 codigo publicado em repositorios, apps mobile ou HTML de site.

Limite de requisicoes

A API Publica aceita ate 100 requisicoes por minuto por chave. Quando o limite e atingido, a API responde com HTTP 429 e voce deve esperar antes de tentar novamente.

Endpoints

POST /send — Enviar mensagem

Envia uma mensagem de texto pelo WhatsApp para o numero informado.

Corpo da requisicao (JSON):

Campo	Tipo	Obrigatorio	Descricao
`phone`	string	sim	Numero completo com DDI + DDD (10 a 15 digitos). Ex: `5511999999999`
`message`	string	sim	Texto da mensagem. Maximo 4096 caracteres.
`session_id`	string	nao	ID de uma sessao WhatsApp especifica da sua conta. Se omitir, usa a sessao padrao. So aceita sessoes da sua propria conta.

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 possiveis:

HTTP	Quando
400	Campo faltando, tipo errado, telefone invalido ou mensagem maior que 4096 caracteres
401	Chave de API ausente ou invalida
403	O `session_id` informado nao pertence a sua conta
429	Limite de requisicoes excedido (100/min)
502	Falha no envio — problema de conexao com WhatsApp
503	WhatsApp nao conectado. Verifique a conexao no painel.

GET /contacts — Listar contatos

Retorna ate 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 ultimas 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..."
    }
  ]
}

GET /stats — Estatisticas da conta

Retorna contadores basicos 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 nao e "perdido" nem "cliente"

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 praticas

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 requisicoes
Valide o telefone antes de enviar — inclua DDI + DDD para evitar erros
Monitore o 503 — se chegar muito, algo esta derrubando o WhatsApp. Veja WhatsApp desconectou
Se voce tem varias sessoes WhatsApp, use session_id explicitamente para garantir que a mensagem sai pelo numero 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 cabecalho e x-api-key (tudo minusculo, com hifen)
Verifique se a chave foi copiada sem espacos extras no inicio ou fim
Confirme no painel que a chave ainda esta ativa

Recebo 503 "WhatsApp nao conectado"

Abra o painel do AgeuBot e confirme que o WhatsApp esta com status "Conectado"
Se voce tem mais de uma sessao, tente passar session_id explicitamente
Apos reconectar, aguarde uns 30 segundos antes de tentar de novo

Recebo 403 ao passar session_id

O session_id passado nao pertence a sua conta. Liste suas sessoes no painel e use um ID valido

Mensagem nao chega ao destinatario

Confirme que o numero tem WhatsApp ativo
Verifique se o numero esta no formato completo (DDI + DDD + numero, so digitos)
O destinatario pode ter bloqueado o seu numero

Proximos passos

Precisa de ajuda com a integracao? Fale com nosso suporte pelo WhatsApp.

Falar com Suporte