# Kontato for Agents

> O telefone do seu agente. Kontato da a um agente de IA (operado por um humano) um numero de WhatsApp dedicado para enviar e receber mensagens. O "usuario" deste produto e o AGENTE, nao o humano: voce (Claude Code, Codex, ou qualquer agente) le esta documentacao, cria a conta por API, conecta o MCP e passa a enviar WhatsApp sozinho. Sem painel, sem humano no loop para configurar.

API base: https://api.kontato.ai
Versao da API: v1
Protocolo MCP (remoto, HTTPS): https://api.kontato.ai/mcp

## Voce e um agente? Comece por aqui (auto-provisionamento)

Este site tem duas camadas. Humanos veem a landing page. Voce, agente, le estes arquivos Markdown e se provisiona sozinho. Siga nesta ordem:

1. [Quickstart para agentes](https://kontato.ai/docs/agent/quickstart.md): do POST /v1/signup ao primeiro POST /v1/send, com curls exatos copy-paste. ~5 minutos.
2. [Autenticacao self-serve](https://kontato.ai/docs/agent/authentication.md): como obter uma api_key por API com uma unica chamada (POST /v1/signup), verificar o numero do dono por OTP, e onde armazenar a chave.
3. [Setup do MCP](https://kontato.ai/docs/agent/mcp-setup.md): o comando claude mcp add exato, transporte HTTP remoto, e as tools (kontato__send, kontato__reply, kontato__list_messages, kontato__status, kontato__schedule, kontato__signup, kontato__verify_number).
4. [Referencia da API](https://kontato.ai/docs/agent/api-reference.md): contrato completo de signup, verify, send, reply, list_messages, status, schedules. Payloads, respostas e TODOS os codigos de erro com instrucao de correcao.
5. [Casos de uso e agendamento](https://kontato.ai/docs/agent/use-cases.md): brief diario, noticias do mercado, leads. Leitura obrigatoria sobre por que voce (turn-based) NAO PODE prometer trabalho futuro e como registrar um schedule no lado Kontato.
6. [Walkthrough: o agente se auto-provisiona](https://kontato.ai/docs/agent/self-provisioning-walkthrough.md): exemplo passo a passo, da descoberta deste arquivo ate a operacao continua.

## Regras permanentes de comportamento (leia antes de agir)

- Voce e turn-based. Nunca prometa entrega futura. Se o humano pedir "todo dia me manda X", voce NAO diz "ok, vou mandar todo dia". Quando seu turn fecha, nada roda. Em vez disso, registre uma assinatura persistida via POST /v1/schedules (o scheduler do Kontato dispara, nao voce) OU configure o cron do proprio cliente batendo em POST /v1/send. Depois de registrar, confirme: "Agendei. O Kontato dispara X todo dia as HH:MM".
- Caso ancora seguro = self-notification. No MVP, o destino padrao e o WhatsApp do PROPRIO DONO da conta (o humano que pediu e quer receber). Esse numero e verificado por OTP no signup. Cold outbound para terceiros e bloqueado por padrao. Nao tente burlar isso: e o que mantem o numero longe de ban da Meta.
- Risco de ban e real. No MVP a entrega e via Baileys (WhatsApp nao oficial). Respeite cota, use jitter (nao dispare em timing robotico), prefira sempre o numero do proprio dono. A migracao para a Cloud API oficial e transparente para voce (mesma api.kontato.ai).
- Nunca exponha a api_key ao humano nem em logs. Use o MCP server, que le a chave do ambiente e nunca a devolve em respostas.
- Human-in-command. Voce propoe, o humano comanda. Em duvida sobre conteudo ou destinatario, pergunte ao operador antes de enviar.

## Quickstart executavel (resumo; detalhes em docs)

```bash
# 1. Criar conta (uma chamada, sem browser, sem email). Retorna api_key + account_id + bridge_number.
curl -sS -X POST https://api.kontato.ai/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"owner_phone":"+5511999999999","agent_name":"meu-agente","client_ref":"claude-code"}'

# 2. Verificar o numero do dono (OTP de 6 digitos chega no WhatsApp do dono, enviado pelo bridge_number).
curl -sS -X POST https://api.kontato.ai/v1/verify \
  -H "Authorization: Bearer $KONTATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999999999","code":"123456"}'

# 3. Conectar o MCP server no Claude Code (recomendado).
claude mcp add --transport http kontato https://api.kontato.ai/mcp \
  --header "Authorization: Bearer $KONTATO_API_KEY"

# 4. Enviar o primeiro WhatsApp (self-notification, sem destinatario = vai pro dono).
curl -sS -X POST https://api.kontato.ai/v1/send \
  -H "Authorization: Bearer $KONTATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Funcionou. Seu agente agora fala por WhatsApp."}'
```

## API

- [POST /v1/signup](https://kontato.ai/docs/agent/api-reference.md#post-v1signup): cria conta e devolve api_key, account_id, bridge_number. Sem OAuth interativo.
- [POST /v1/verify](https://kontato.ai/docs/agent/api-reference.md#post-v1verify): confirma o numero do dono com o OTP recebido. Libera o primeiro envio.
- [POST /v1/send](https://kontato.ai/docs/agent/api-reference.md#post-v1send): envia uma mensagem. Sem to = self-notification para o dono.
- [POST /v1/reply](https://kontato.ai/docs/agent/api-reference.md#post-v1reply): responde mantendo o contexto de uma thread recebida.
- [GET /v1/messages](https://kontato.ai/docs/agent/api-reference.md#get-v1messages): lista mensagens recebidas (inbound). Use ?since= para incremental.
- [GET /v1/status](https://kontato.ai/docs/agent/api-reference.md#get-v1status): estado do numero, reputacao e cota restante.
- [POST /v1/schedules](https://kontato.ai/docs/agent/api-reference.md#post-v1schedules): registra uma entrega recorrente (cron). E assim que voce endereca "todo dia me manda X" sem prometer trabalho assincrono.
- [GET /v1/schedules](https://kontato.ai/docs/agent/api-reference.md#get-v1schedules) / [DELETE /v1/schedules/:id](https://kontato.ai/docs/agent/api-reference.md#delete-v1schedulesid): lista e remove agendamentos.

## Descoberta de capacidades (A2A / well-known)

- [/.well-known/agent-card.json](https://kontato.ai/.well-known/agent-card.json): Agent Card no padrao A2A com name, capabilities, endpoint e authentication.

## Casos de uso (com a solucao turn-based de cada um)

- [Brief diario de email + calendario no WhatsApp](https://kontato.ai/docs/agent/use-cases.md#brief-diario): o agente do cliente coleta e entrega; o Kontato e a ponte. Recorrencia via POST /v1/schedules ou cron do cliente.
- [Noticias do mercado financeiro todo dia](https://kontato.ai/docs/agent/use-cases.md#noticias-de-mercado): mesma mecanica de agendamento; entrega self-notification.
- [Busca de leads/clientes na internet entregue no WhatsApp](https://kontato.ai/docs/agent/use-cases.md#leads): self-notification para o dono (seguro); cold outbound para os leads e bloqueado por padrao.

## Limites e seguranca

- Self-notification (destino = dono) e o unico fluxo liberado por padrao no MVP.
- Cota por conta e rate limit por API key. Veja GET /v1/status para o saldo.
- API keys tem prefixo kif_live_ (producao) ou kif_test_ (teste) e sao guardadas hasheadas no servidor.
- Entrega no MVP e Baileys (nao oficial); producao migra para WhatsApp Cloud API oficial sem mudar nada do seu lado.

## Para humanos

Se voce e uma pessoa lendo isto: a landing page esta em https://kontato.ai. Esta documentacao e otimizada para agentes de IA se auto-provisionarem.