Uazapi — Referência técnica¶

API self-hosted de WhatsApp usada pela Gita. Doc técnico pra agentes (comms) e devs. Cliente JS de referência: server/automations/uazapi.js

URL base¶

https://grupogita.uazapi.com

Autenticação¶

Header obrigatório em toda chamada:

token: <UAZAPI_TOKEN_DA_INSTANCIA>

Cada instância tem seu próprio token. Mesma URL serve todas.

Instâncias da Gita¶

Slug interno	Token (env var)	Número	Uso
`gita`	`UAZAPI_TOKEN_GITA`	556191502969	Número oficial Gita — automações, atendimento, alertas
`tay`	`UAZAPI_TOKEN_TAY`	(pessoal Tay)	Número pessoal — automações pessoais da CEO

Nunca commita o token. Tokens vivem em .env local (gitignored) ou em Easypanel pro server.

Endpoints usados pelo agente `comms` (Onda 1)¶

POST `/send/text` — envio pra contato¶

curl -X POST "$UAZAPI_URL/send/text" \
  -H "token: $UAZAPI_TOKEN_GITA" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5531987654321",
    "text": "Mensagem aqui"
  }'

Body: - number — e164 sem + (ex: 5531987654321). Aceita também [email protected]. - text — string, suporta quebra de linha (\n) e formatação WhatsApp (*bold*, _italic_, ~strike~, `mono`).

Resposta esperada: 200 com JSON contendo messageId ou similar. Erro: 4xx/5xx.

POST `/message/send/text` — envio pra grupo¶

curl -X POST "$UAZAPI_URL/message/send/text" \
  -H "token: $UAZAPI_TOKEN_GITA" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "[email protected]",
    "text": "Mensagem aqui"
  }'

Body: - number — group_id terminado em @g.us (formato [email protected] ou [email protected]) - text — mesma regra do envio de contato

Existem implementações onde grupo também aceita /send/text. Padronizar em /message/send/text pra grupos no agente.

Formato de números e IDs¶

Tipo	Formato	Exemplo
Contato (e164)	`<código-país><DDD><número>`	`5531987654321`
Contato (com sufixo)	`<e164>@c.us`	`[email protected]`
Grupo	`<group-id>@g.us`	`[email protected]`

Normalização recomendada antes de mandar: - Remove +, espaços, hífens, parênteses - Garante que começa com código país (Brasil = 55) - Pra Brasil mobile: 55 + DDD (2 dígitos) + 9 + 8 dígitos = 13 dígitos total

Como obter o group_id¶

Não há endpoint público pra listar grupos. Opções:

Admin Uazapi (https://grupogita.uazapi.com) → instância → mensagens recentes → copia o from/chat_id do grupo
Mensagem teste: alguém manda mensagem no grupo, busca no log Uazapi via webhook recebido
Inspect manual: abrir WhatsApp Web logado na instância → DevTools → ver chat-id

Salvar em data/whatsapp/grupos.md pra reuso.

Endpoints disponíveis mas FORA do escopo da Onda 1¶

Implementados em server/automations/uazapi.js mas não usados pelo agente comms ainda:

Endpoint	Uso	Quando incluir
`/send/media`	Enviar PDF, imagem, áudio	Onda 2 ou quando Tay pedir
`/group/create`	Criar grupo novo	Quando precisar de automação de criação
`/instance/all`	Listar instâncias (admin token)	Diagnóstico
`/instance/status`	Status de uma instância (online/offline)	Healthcheck
`/message/download`	Baixar mídia recebida (base64)	Quando processar mensagem entrante

Tratamento de erros comuns¶

Erro	Causa provável	O que fazer
`401 Unauthorized`	Token errado ou faltando	Verificar `.env` local
`404 Not Found`	Endpoint errado ou instância desconectada	Bater em `/instance/status`
`400 Bad Request`	Número malformado, body inválido	Validar formato e164
`5xx`	Uazapi instável	Retry depois de 30s; se persistir, chama Junior
Timeout	Rede ou Uazapi sobrecarregado	Não retry automático — pode duplicar mensagem

Boas práticas¶

Sempre confirmar antes de enviar (regra do agente comms). WhatsApp não tem desfazer.
Não fazer broadcast em loop: se precisar mandar pra N pessoas, faz com confirmação por destinatário.
Respeitar rate limit: API Uazapi pode rate-limitar se pingar muito rápido. Espaçar 1-2s entre envios sequenciais.
Logging: Onda 1 usa apenas log do Bash do Claude Code. Onda 2 vai persistir em Supabase (comms_log).

Links¶

Cliente JS de referência: server/automations/uazapi.js (CommonJS, fetch-based)
Cliente TS de referência: ~/projetos/gita-agents/packages/engine/src/integrations/whatsapp/uazapi.ts
Admin Uazapi: https://grupogita.uazapi.com
Memory: ver MEMORY.md (decisões e endpoints integrados)