JoeBot API

Puxe métricas e gerencie a sua comunidade de WhatsApp — comandos, mensagens agendadas e moderação — direto pelo seu sistema, planilha ou integração.

Introdução

A API é REST, fala JSON e usa autenticação por chave. Toda requisição parte da mesma base:

https://vpvsrjkotstvjywhuacr.supabase.co/functions/v1/api/v1

Cada chave enxerga apenas os grupos da sua conta. Você não consegue ler nem escrever em grupos de outros clientes.

Autenticação

Gere uma chave no painel: joebot.com.br/dashboard → aba API → Gerar chave. Ela aparece uma única vez — copie e guarde.

Envie a chave em todas as requisições no header Authorization:

Authorization: Bearer joe_live_sua_chave_aqui

Escopos

Escopo	Permite
`metrics:read`	Ler métricas e listar comandos / agendamentos / palavras (todos os GET).
`write`	Criar e remover (os POST e DELETE). Ative o “Permitir escrita” ao gerar a chave.

Comece com uma chave só leitura. Gere uma com escrita apenas para a integração que realmente precisa alterar dados.

Erros

Erros vêm com o status HTTP e um corpo { "error": "...", "detail": "..." }.

Status	error	Quando
401	`unauthorized`	Chave ausente, inválida ou revogada.
403	`forbidden`	Chave sem escopo `write` tentando criar/remover.
404	`not_found`	Grupo ou registro não pertence à sua chave.
400	`bad_request`	Faltou campo obrigatório ou valor inválido.

Métricas

GET/metrics

Mensagens por dia (hoje, 7d, 30d) e — quando você passa um grupo — o ranking de quem mais participa.

Query params

Param		Descrição
`group`	opcional	JID do grupo (ex `1203...@g.us`). Sem ele, retorna todos os seus grupos.
`range`	opcional	`7d`, `30d` (padrão) ou `90d` — janela da série diária.

Exemplo

# um grupo, últimos 7 dias (inclui top usuários)
curl "$BASE/metrics?group=1203...@g.us&range=7d" \
  -H "Authorization: Bearer joe_live_..."

// 200 OK
{
  "range": "7d",
  "grupos": [{
    "group_jid": "1203...@g.us",
    "grupo_nome": "Minha Comunidade",
    "mensagens": { "hoje": 12, "7d": 310, "30d": 1240 },
    "serie": [{ "dia": "2026-08-19", "total": 25 }]
  }],
  "top_usuarios": [{ "nome": "Ana", "total": 48 }]
}

Comandos

GET/commands

Lista os comandos do grupo. Query: group obrigatório.

POST/commandswrite

Cria um comando. O Joe responde na comunidade quando alguém digitar.

DELETE/commands/{id}write

Remove o comando pelo id.

Corpo (POST)

Campo		Descrição
`group`	obrig.	JID do grupo.
`comando`	obrig.	O gatilho, ex `/site` (a barra é adicionada se faltar).
`tipo`	opcional	`text` (padrão) ou `image` / `document` / `audio` / `video`.
`resposta`	—	Obrigatória no `text`. Quando é mídia, vira a legenda (opcional).
`media_url`	—	Obrigatória quando `tipo` ≠ `text`. URL pública da imagem/arquivo.

curl -X POST "$BASE/commands" -H "Authorization: Bearer joe_live_..." \
  -d '{"group":"1203...@g.us","comando":"/site","resposta":"https://exemplo.com"}'

// 201 Created
{ "ok": true, "command": { "id": "uuid", "comando": "/site", "resposta": "..." } }

Mensagens agendadas

GET/messages

Lista os agendamentos do grupo. Query: group obrigatório.

POST/messageswrite

Agenda uma mensagem única. O Joe envia sozinho no horário marcado.

DELETE/messages/{id}write

Cancela um agendamento.

Corpo (POST)

Campo		Descrição
`group`	obrig.	JID do grupo.
`texto`	obrig.	A mensagem — ou a pergunta quando é enquete.
`quando`	obrig.	Data/hora no futuro em ISO 8601, ex `2026-08-25T20:00:00-03:00`.
`tipo`	opcional	`text` (padrão), `poll` (enquete), `image` ou `audio`.
`opcoes`	—	Obrigatória quando `tipo=poll`: array com 2+ opções.
`media_url`	—	Obrigatória quando `tipo=image`/`audio`. URL pública (o `texto` vira legenda).

# mensagem
curl -X POST "$BASE/messages" -H "Authorization: Bearer joe_live_..." \
  -d '{"group":"1203...@g.us","texto":"Live hoje 20h!","quando":"2026-08-25T20:00:00-03:00"}'

# enquete agendada
curl -X POST "$BASE/messages" -H "Authorization: Bearer joe_live_..." \
  -d '{"group":"1203...@g.us","tipo":"poll","texto":"Qual tema?","opcoes":["Arduino","Robótica","IA"],"quando":"2026-08-25T20:00:00-03:00"}'

Moderação

GET/moderation

Lista as palavras bloqueadas. Query: group obrigatório.

POST/moderationwrite

Bloqueia uma palavra — o Joe apaga na hora qualquer mensagem que a contenha (o Joe precisa ser admin do grupo).

DELETE/moderation/{id}write

Desbloqueia a palavra.

Corpo (POST)

Campo		Descrição
`group`	obrig.	JID do grupo.
`palavra`	obrig.	A palavra a bloquear (case-insensitive).

curl -X POST "$BASE/moderation" -H "Authorization: Bearer joe_live_..." \
  -d '{"group":"1203...@g.us","palavra":"spam"}'

JoeBot API v1 · beta · dúvidas? fale com o suporte no painel. Defina $BASE como a URL base acima para rodar os exemplos.