Documentação da API

API de WhatsApp da HypeAi Integra

Envie e receba mensagens de WhatsApp por uma API REST 100% compatível com a Cloud API da Meta. Sem aprovação de app, sem BSP: gere uma chave, aponte para um número conectado e comece.

Começar

Visão geral

O gateway da HypeAi é um proxy transparente da Cloud API da Meta, organizado por número (phone_number_id). Tudo o que existe na documentação oficial da Meta funciona aqui: você só troca o domínio e o token. Em cima disso, a HypeAi cuida de autenticação por chave, limite de uso, idempotência, rastreamento e erros padronizados.

Endpoint canônico de envio: POST /v1/{phone_number_id}/messages.
Qualquer outro caminho sob /v1/{phone_number_id}/... é repassado para a Meta.
Respostas trazem X-Request-Id e X-Hypeai-Latency-Ms para rastreio.

Já tem conta? Abra o Explorer para montar e testar as chamadas com as suas chaves e os seus números preenchidos.

Endpoint base

https://api.hypeai.com.br/v1/{phone_number_id}/messages

Começar

Autenticação

Toda requisição leva a sua chave no header Authorization, no formato Bearer. As chaves começam com hai_live_ (produção) ou hai_test_ (teste).

Crie e gerencie chaves no painel, na aba Desenvolvedor.
A chave completa aparece uma única vez, no momento da criação. Guarde num cofre.
Ao rotacionar, a chave antiga continua válida por 24h para você migrar sem downtime.

Nunca exponha a chave no front-end nem em repositórios públicos. Se vazar, revogue e gere outra.

Header

Authorization: Bearer hai_live_SEU_TOKEN

Começar

Primeiro envio

Monte a chamada, copie o código (cURL, JavaScript ou Python) e rode no seu terminal, no n8n, Make ou qualquer cliente HTTP. O Explorer gera o código pronto (e, logado, já preenche as suas chaves e números).

Abrir o Explorer interativo no app →

Enviar mensagens

Mensagem de texto

Texto livre. Só funciona dentro da janela de 24h após a última mensagem do contato.

Campo	Tipo	Descrição
`to`*	string	Número do destinatário com DDI, só dígitos (ex.: `5511999999999`).
`type`*	string	Use `"text"`.
`text.body`*	string	O texto. Até 4096 caracteres.

curl -X POST \
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "text",
  "text": {
    "body": "Olá! 👋 Sua mensagem via HypeAi Integra.",
    "preview_url": true
  }
}'

const res = await fetch(
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "text",
      "text": {
        "body": "Olá! 👋 Sua mensagem via HypeAi Integra.",
        "preview_url": true
      }
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "text",
      "text": {
        "body": "Olá! 👋 Sua mensagem via HypeAi Integra.",
        "preview_url": True
      }
    },
)
print(res.status_code, res.json())

Enviar mensagens

Template

Template aprovado é o único jeito de iniciar conversa fora da janela de 24h. Para preencher variáveis, adicione components (veja a referência da Meta).

Campo	Tipo	Descrição
`type`*	string	Use `"template"`.
`template.name`*	string	Nome do template aprovado (ex.: `hello_world`).
`template.language.code`*	string	Código do idioma (ex.: `pt_BR`, `en_US`).
`template.components`	array	Variáveis do corpo, cabeçalho e botões (opcional).

curl -X POST \
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": {
      "code": "en_US"
    }
  }
}'

const res = await fetch(
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "template",
      "template": {
        "name": "hello_world",
        "language": {
          "code": "en_US"
        }
      }
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "template",
      "template": {
        "name": "hello_world",
        "language": {
          "code": "en_US"
        }
      }
    },
)
print(res.status_code, res.json())

Enviar mensagens

Mídia (imagem, vídeo, áudio, documento)

Envie mídia por URL pública (link) ou por media id (id, após o upload; veja Upload de mídia). O exemplo ao lado usa imagem; vídeo, áudio e documento seguem a mesma forma, trocando a chave image por video, audio ou document.

Campo	Tipo	Descrição
`type`*	string	`"image"`, `"video"`, `"audio"` ou `"document"`.
`<tipo>.link`	string	URL pública do arquivo (ou use `id`).
`<tipo>.id`	string	ID de mídia já enviada à Meta.
`<tipo>.caption`	string	Legenda (imagem, vídeo, documento).
`document.filename`	string	Nome exibido do arquivo.

curl -X POST \
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "image",
  "image": {
    "link": "https://exemplo.com/foto.jpg"
  }
}'

const res = await fetch(
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "image",
      "image": {
        "link": "https://exemplo.com/foto.jpg"
      }
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "image",
      "image": {
        "link": "https://exemplo.com/foto.jpg"
      }
    },
)
print(res.status_code, res.json())

Enviar mensagens

Botões e listas

Mensagens interativas (dentro da janela de 24h). Botões: até 3 respostas rápidas. Listas: um menu com seções e itens. O exemplo mostra botões; a lista usa interactive.type: "list" comaction.sections[].rows[].

Campo	Tipo	Descrição
`type`*	string	Use `"interactive"`.
`interactive.type`*	string	`"button"` ou `"list"`.
`interactive.body.text`*	string	Texto principal.
`interactive.action.buttons[]`	array	Botões (máx. 3): `{ type:"reply", reply:{ id, title } }`.
`interactive.action.sections[]`	array	Para listas: seções com `rows[]` (`id`, `title`, `description?`).

curl -X POST \
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Como podemos ajudar?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "btn_1",
            "title": "Falar com vendas"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "btn_2",
            "title": "Suporte"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "btn_3",
            "title": "Outro assunto"
          }
        }
      ]
    }
  }
}'

const res = await fetch(
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "interactive",
      "interactive": {
        "type": "button",
        "body": {
          "text": "Como podemos ajudar?"
        },
        "action": {
          "buttons": [
            {
              "type": "reply",
              "reply": {
                "id": "btn_1",
                "title": "Falar com vendas"
              }
            },
            {
              "type": "reply",
              "reply": {
                "id": "btn_2",
                "title": "Suporte"
              }
            },
            {
              "type": "reply",
              "reply": {
                "id": "btn_3",
                "title": "Outro assunto"
              }
            }
          ]
        }
      }
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "interactive",
      "interactive": {
        "type": "button",
        "body": {
          "text": "Como podemos ajudar?"
        },
        "action": {
          "buttons": [
            {
              "type": "reply",
              "reply": {
                "id": "btn_1",
                "title": "Falar com vendas"
              }
            },
            {
              "type": "reply",
              "reply": {
                "id": "btn_2",
                "title": "Suporte"
              }
            },
            {
              "type": "reply",
              "reply": {
                "id": "btn_3",
                "title": "Outro assunto"
              }
            }
          ]
        }
      }
    },
)
print(res.status_code, res.json())

Enviar mensagens

Localização, contato e reação

Tipos adicionais suportados pelo proxy:

Localização (type: "location"): latitude, longitude, e opcionalmente name/address.
Contato (type: "contacts"): array com name e phones[].
Reação (type: "reaction"): message_id (o wamid recebido) + emoji.

Selecione esses endpoints no Explorer para ver o corpo exato de cada um.

curl -X POST \
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "location",
  "location": {
    "latitude": -23.5613,
    "longitude": -46.6565,
    "name": "Av. Paulista",
    "address": "Av. Paulista, 1000 - São Paulo"
  }
}'

const res = await fetch(
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "location",
      "location": {
        "latitude": -23.5613,
        "longitude": -46.6565,
        "name": "Av. Paulista",
        "address": "Av. Paulista, 1000 - São Paulo"
      }
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "messaging_product": "whatsapp",
      "to": "5511999999999",
      "type": "location",
      "location": {
        "latitude": -23.5613,
        "longitude": -46.6565,
        "name": "Av. Paulista",
        "address": "Av. Paulista, 1000 - São Paulo"
      }
    },
)
print(res.status_code, res.json())

Conversa & status

A janela de 24 horas

O WhatsApp separa dois tipos de mensagem do negócio para o cliente:

Resposta de serviço: dentro de 24h desde a última mensagem do contato, pode mandar texto, mídia e interativos livremente.
Iniciada pelo negócio: fora da janela de 24h, só template aprovado. Qualquer outro tipo é recusado pela Meta.

Se você receber um erro pedindo template fora da janela, é exatamente isso: use Template para reabrir a conversa.

Conversa & status

Lida, digitação e status de entrega

Confirme leitura e mostre que está digitando usando o wamid que chegou no seu webhook:

Marcar como lida (✓✓ azuis): { status: "read", message_id }.
Digitando…: adicione typing_indicator: { type: "text" }. Some sozinho em ~25s ou quando você responde.
Status de envio (sent, delivered, read, failed) chega pelo webhook message_status.

curl -X POST \
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgM..."
}'

const res = await fetch(
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "messaging_product": "whatsapp",
      "status": "read",
      "message_id": "wamid.HBgM..."
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID/messages",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "messaging_product": "whatsapp",
      "status": "read",
      "message_id": "wamid.HBgM..."
    },
)
print(res.status_code, res.json())

Número & templates

Dados do número

Consulte os metadados do número conectado: nome verificado, número exibido, qualidade e status de verificação. É um GET simples em /v1/{phone_number_id}.

curl -X GET \
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID?fields=verified_name,display_phone_number,quality_rating,code_verification_status" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN"

const res = await fetch(
  "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID?fields=verified_name,display_phone_number,quality_rating,code_verification_status",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
    },
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.get(
    "https://api.hypeai.com.br/v1/PHONE_NUMBER_ID?fields=verified_name,display_phone_number,quality_rating,code_verification_status",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
    },
)
print(res.status_code, res.json())

Número & templates

Templates

Como tudo é repassado à Meta, você gerencia templates pelos mesmos endpoints da Cloud API (listar, criar, conferir status de aprovação). Pelo painel da HypeAi há uma UI guiada para isso; pela API, use os caminhos da Meta sob o seu número/WABA.

Referência completa: Message Templates (Meta).

Listar templates

GET https://api.hypeai.com.br/v1/{phone_number_id}/message_templates
Authorization: Bearer hai_live_SEU_TOKEN

Número & templates

Upload e download de mídia

Para enviar mídia sem URL pública, faça upload primeiro e use o id retornado nas mensagens. Para baixar mídia recebida, use o media_id que chega no webhook.

Upload: POST /v1/{phone_number_id}/media (multipart) → retorna { "id": "..." }.
Download: GET /v1/{phone_number_id}/media/{media_id}.

Upload

curl -X POST \
  "https://api.hypeai.com.br/v1/{phone_number_id}/media" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -F "messaging_product=whatsapp" \
  -F "file=@/caminho/arquivo.jpg"

Webhooks

Receber eventos

Registre uma URL de webhook no painel (aba Integrações) e a HypeAi entrega os eventos do seu número via POST em JSON. O corpo segue o envelope ao lado.

Eventos

messages: mensagens recebidas (texto, mídia, interativo, localização, contato).
message_status: status de envio (sent, delivered, read, failed).
templates: mudança de status de um template (aprovado/rejeitado).
account_update: qualidade do número, limites de tier, restrições da conta.
smb_message_echoes (coexistência, opt-in explícito): eco das mensagens que você envia pelo app WhatsApp Business do celular — para o seu sistema exibir a conversa completa. Direção invertida:from = o seu número, to = o cliente. Nunca chega dentro de messages.

Entrega e reentrega

Responda 2xx rápido. Em falha, reentregamos com backoff (1m, 5m, 30m, 2h, 12h; até 5 tentativas, depois dead-letter). O header X-HypeAi-Event-Id é estável entre tentativas: deduplique por ele.

{
  "object": "whatsapp_business_account",
  "event": "messages",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5511999999999",
              "phone_number_id": "123456789012345"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria"
                },
                "wa_id": "5511988887777"
              }
            ],
            "messages": [
              {
                "from": "5511988887777",
                "id": "wamid.HBgNNTUxMTk4...",
                "timestamp": "1718800000",
                "type": "text",
                "text": {
                  "body": "Olá!"
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "received_at": "2026-06-19T12:00:00.000Z"
}

{
  "object": "whatsapp_business_account",
  "event": "message_status",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "message_status",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5511999999999",
              "phone_number_id": "123456789012345"
            },
            "statuses": [
              {
                "id": "wamid.HBgNNTUx...",
                "status": "delivered",
                "timestamp": "1718800050",
                "recipient_id": "5511988887777"
              }
            ]
          }
        }
      ]
    }
  ],
  "received_at": "2026-06-19T12:00:50.000Z"
}

{
  "object": "whatsapp_business_account",
  "event": "smb_message_echoes",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "smb_message_echoes",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5511999999999",
              "phone_number_id": "123456789012345"
            },
            "message_echoes": [
              {
                "from": "5511999999999",
                "to": "5511988887777",
                "id": "wamid.HBgNNTUxMTk4...",
                "timestamp": "1718800100",
                "type": "text",
                "text": {
                  "body": "Respondi pelo celular 👍"
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "received_at": "2026-06-19T12:01:40.000Z"
}

X-HypeAi-Event: messages
X-HypeAi-Signature-256: sha256=<hmac-sha256 do corpo, com seu secret>
X-HypeAi-Event-Id: 3f2a...-uuid    # estável entre re-entregas do MESMO evento — deduplique por ele
X-HypeAi-Delivery-Id: 7b1f...-uuid    # muda a cada tentativa
X-HypeAi-Delivery-Attempt: 1

Webhooks

Validar a assinatura

Cada entrega vem assinada com HMAC-SHA256 do corpo cru, usando o secret do seu webhook, no header X-HypeAi-Signature-256 (prefixado por sha256=). Valide antes de confiar no payload.

Use o corpo exatamente como recebido (raw), não o JSON re-serializado. Qualquer reordenação de chaves muda o hash.

O secret é revelado uma única vez (na criação). Perdeu ou suspeita de vazamento? Rotacione — no painel (Integrações → editar webhook → Rotacionar secret) ou pela API de Gestão (action: "rotate"): o novo secret é revelado uma vez e passa a assinar as entregas na hora.

import crypto from "node:crypto";

// rawBody = corpo exato recebido (string), NÃO o JSON re-serializado.
function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(header, expected)

Referência

Idempotência

Em POST, envie um header Idempotency-Key (qualquer string única por operação). Repetir a chamada com a mesma chave e o mesmo corpo devolve a resposta em cache (24h) sem reenviarà Meta. A resposta replicada traz X-Hypeai-Idempotent-Replayed: true.

Mesma chave com corpo diferente retorna 422 (hypeai_type: "idempotency").

Header

Idempotency-Key: pedido-12345

Referência

Limites de uso

O limite padrão é de 120 requisições por minuto por chave (ajustável por chave). Ao estourar, você recebe 429 com o header Retry-After (segundos). Espere esse tempo antes de tentar de novo.

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Referência

Erros

Erros seguem o mesmo formato da Meta, com um campo extra hypeai_type para você tratar programaticamente. O header X-Request-Id ajuda no suporte.

HTTP	hypeai_type	Significado
401	auth	Chave de API ausente, inválida ou revogada.
403 / 503	unavailable	Conta arquivada ou credencial do WhatsApp indisponível.
404	not_found	phone_number_id não pertence à sua conta.
413	payload_too_large	Corpo acima do limite (100MB).
422	idempotency	Idempotency-Key reusada com corpo diferente.
429	rate_limit	Limite de requisições excedido (veja Retry-After).
502	upstream	Falha ao falar com a Meta.
504	upstream_timeout	Meta não respondeu a tempo (25s).

Corpo de erro

{
  "error": {
    "message": "Mensagem fora da janela de 24h. Use um template aprovado.",
    "type": "HypeAiError",
    "code": 400,
    "error_subcode": null,
    "fbtrace_id": "A1b2C3...",
    "hypeai_type": "upstream"
  }
}

Referência exaustiva de campos: Cloud API da Meta. Precisa de uma chave? Acesse o painel.

API de Gestão

beta

API HypeAi Integra

Além de enviar mensagens, a mesma chave hai_live_ opera os dados e a configuração da sua conta: analytics, números, templates, webhooks e integrações. Tudo escopado à conta da chave — você só enxerga e altera o que é seu.

Começar

Visão geral

A API de Gestão expõe as operações integra_* sobre uma base de recursos emhttps://api.hypeai.com.br/<recurso>. Cada recurso recebe um POST com um corpo JSON que carrega a operação no campo action (ex.: list, create, delete) — mais os parâmetros daquela operação.

Autenticação idêntica à API de WhatsApp: header Authorization: Bearer hai_live_….
Tudo é escopado pela chave: a conta dona da chave é a fronteira — sem vazamento entre clientes.
Respostas em JSON. Operações sensíveis (criar webhook, configurar Chatwoot) devolvem segredos uma única vez — perdeu um secret de webhook? Rotacione (action: "rotate") em vez de recriar.

Contrato beta. Hoje as chamadas são POST { action } por recurso. Vamos evoluir para REST por recurso (com OpenAPI) — quando isso acontecer, o caminho antigo continua respondendo durante a transição. Use em produção, mas fixe a versão e acompanhe o changelog.

Padrão das chamadas

POST https://api.hypeai.com.br/<recurso>
Authorization: Bearer hai_live_SEU_TOKEN
Content-Type: application/json

{ "action": "list" }

Começar

Autenticação

É a mesma chave da API de WhatsApp. Gere e gerencie na aba Desenvolvedor do painel; uma chave de agência (escopo agência) também opera vários clientes, conforme a sua permissão.

Já tem conta? Abra o Explorer e ele já vem com as suas chaves.

Header

Authorization: Bearer hai_live_SEU_TOKEN

Começar

Primeiro request

Monte a chamada, copie o código (cURL, JavaScript ou Python) e rode onde quiser. O Explorer gera o código pronto, com a sua chave.

Abrir o Explorer interativo no app →

Endpoints

Analytics da conta

Métricas ao vivo da Meta agregadas pela HypeAi (conversas, custo estimado, entrega), com cache curto. Informe operiod desejado.

Campo	Tipo	Descrição
`period`	string	Janela: `24h`, `7d`, `30d` ou `90d` (padrão `7d`).

curl -X POST \
  "https://api.hypeai.com.br/client-analytics" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "7d"
}'

const res = await fetch(
  "https://api.hypeai.com.br/client-analytics",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "period": "7d"
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/client-analytics",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "period": "7d"
    },
)
print(res.status_code, res.json())

Endpoints

Uso & pacotes de mensagens

Pacotes de mensagens (quota-manage): limite mensal de envios por número — ideal para revender planos com franquia — ou da conta inteira, com rollover opcional (saldo não usado acumula para o mês seguinte, com vencimento configurável). Ao esgotar, os envios respondem 429 quota_exceededaté o próximo ciclo (ou apenas geram aviso, no modo warn). Alertas automáticos em 80% e 100% chegam nos seus webhooks como evento quota.threshold.

Campo	Tipo	Descrição
`action`	string	`list` (saldo/consumo) ou `set` (criar/editar).
`phone_number_id`	string	Opcional em `set`: escopo por número. Omita para a conta inteira.
`monthly_allowance`	integer	Limite mensal de mensagens enviadas (todos os caminhos: API, bot, chat).
`rollover_enabled`	boolean	Acumular saldo não usado (padrão `false`).
`rollover_expiry_months`	integer	Saldo acumula por até X meses (omita = sem vencimento).
`mode`	string	`enforce` bloqueia ao esgotar (padrão); `warn` só avisa.
`active`	boolean	`false` remove o pacote.

O consumo conta toda mensagem aceita pela Meta (2xx) — falhas e re-tentativas idempotentes não gastam pacote. O custo Meta estimado por categoria está no payload estimated do Analytics acima.

curl -X POST \
  "https://api.hypeai.com.br/quota-manage" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "set",
  "phone_number_id": "123456789012345",
  "monthly_allowance": 1000,
  "rollover_enabled": false,
  "rollover_expiry_months": 3
}'

const res = await fetch(
  "https://api.hypeai.com.br/quota-manage",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "action": "set",
      "phone_number_id": "123456789012345",
      "monthly_allowance": 1000,
      "rollover_enabled": false,
      "rollover_expiry_months": 3
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/quota-manage",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "action": "set",
      "phone_number_id": "123456789012345",
      "monthly_allowance": 1000,
      "rollover_enabled": False,
      "rollover_expiry_months": 3
    },
)
print(res.status_code, res.json())

Endpoints

Números & perfil

Operações sobre os números conectados e o perfil comercial de cada um (em number-profile-manage e sync-phone-numbers):

Ler perfil: { action: "get", phone_number_id }.
Editar perfil: { action: "update", phone_number_id, about?, description?, … } (verified_name é read-only).
Re-sincronizar números: POST /sync-phone-numbers (atualiza nome, qualidade e tier a partir da Meta).

Campo	Tipo	Descrição
`action`*	string	`"get"` ou `"update"`.
`phone_number_id`*	string	O número alvo (veja-os no painel, aba Números).
`about / description / …`	string	Campos do perfil (address, email, websites[], vertical) — apenas em `update`.

curl -X POST \
  "https://api.hypeai.com.br/number-profile-manage" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "get",
  "phone_number_id": "123456789012345"
}'

const res = await fetch(
  "https://api.hypeai.com.br/number-profile-manage",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "action": "get",
      "phone_number_id": "123456789012345"
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/number-profile-manage",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "action": "get",
      "phone_number_id": "123456789012345"
    },
)
print(res.status_code, res.json())

Endpoints

Templates (ciclo de vida completo)

Crie, edite, apague e acompanhe a aprovação dos seus templates pela API (recurso manage-templates, padrão { action }). O campo template segue o formato cru da Cloud API — cobre todos os tipos (header text/mídia/location, body com variáveis, footer, botões, OTP):

Criar: { action: "create", template } — entra PENDING; a aprovação é assíncrona (minutos a 24h+). Recomendado allow_category_change: true.
Mídia no header (IMAGE/VIDEO/DOCUMENT): antes do create, { action: "upload_example", file_url } devolve o handle — use-o em example.header_handle.
Editar: { action: "update", template_id, template: { components } } (volta a PENDING; Meta limita a 1 edição/24h e 10/mês).
Remover: { action: "delete", name } (todas as línguas; template_id restringe a uma).
Status: assine o evento templates no seu webhook (push de APPROVED/REJECTED) ou force a releitura em client-templates-status ({ force: true }).

Connect / chave de agência: passe client_id do sub-cliente para o cliente final do seu SaaS criar e gerenciar os próprios templates de dentro do seu produto. Multi-WABA: informe credential_id.

curl -X POST \
  "https://api.hypeai.com.br/manage-templates" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "create",
  "template": {
    "name": "confirmacao_pedido",
    "language": "pt_BR",
    "category": "UTILITY",
    "allow_category_change": true,
    "components": [
      {
        "type": "BODY",
        "text": "Oi {{1}}, seu pedido {{2}} foi confirmado!",
        "example": {
          "body_text": [
            [
              "Maria",
              "#123"
            ]
          ]
        }
      }
    ]
  },
  "credential_id": "uuid da credencial",
  "client_id": "uuid do sub-cliente"
}'

const res = await fetch(
  "https://api.hypeai.com.br/manage-templates",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "action": "create",
      "template": {
        "name": "confirmacao_pedido",
        "language": "pt_BR",
        "category": "UTILITY",
        "allow_category_change": true,
        "components": [
          {
            "type": "BODY",
            "text": "Oi {{1}}, seu pedido {{2}} foi confirmado!",
            "example": {
              "body_text": [
                [
                  "Maria",
                  "#123"
                ]
              ]
            }
          }
        ]
      },
      "credential_id": "uuid da credencial",
      "client_id": "uuid do sub-cliente"
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/manage-templates",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "action": "create",
      "template": {
        "name": "confirmacao_pedido",
        "language": "pt_BR",
        "category": "UTILITY",
        "allow_category_change": True,
        "components": [
          {
            "type": "BODY",
            "text": "Oi {{1}}, seu pedido {{2}} foi confirmado!",
            "example": {
              "body_text": [
                [
                  "Maria",
                  "#123"
                ]
              ]
            }
          }
        ]
      },
      "credential_id": "uuid da credencial",
      "client_id": "uuid do sub-cliente"
    },
)
print(res.status_code, res.json())

Endpoints

Webhooks de saída

Gerencie os webhooks que recebem os eventos do seu número (recurso webhooks-manage). O exemplo mostra a criação; o corpo muda só o action:

Listar: { action: "list" }.
Criar: { action: "create", name, url, events[], all_numbers } — devolve o secret HMAC uma única vez.
Editar: { action: "update", id, events[], url, is_active } — events substitui a lista atual (inclua os já assinados). Ex.: adicionar smb_message_echoes (coexistência).
Rotacionar secret: { action: "rotate", id } — devolve um novo secret uma única vez, sem recriar o webhook. Use se perdeu o secret ou suspeita de vazamento; as entregas passam a ser assinadas com o novo na hora.
Remover: { action: "delete", id }.
Testar / reenviar: { action: "test", … } e { action: "resend", delivery_id }.

A validação da assinatura HMAC e o envelope dos eventos estão documentados na API de WhatsApp → Webhooks (troque o seletor de API no topo).

curl -X POST \
  "https://api.hypeai.com.br/webhooks-manage" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "create",
  "name": "Meu webhook",
  "url": "https://exemplo.com/webhook",
  "events": [
    "messages",
    "message_status"
  ],
  "all_numbers": true
}'

const res = await fetch(
  "https://api.hypeai.com.br/webhooks-manage",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "action": "create",
      "name": "Meu webhook",
      "url": "https://exemplo.com/webhook",
      "events": [
        "messages",
        "message_status"
      ],
      "all_numbers": true
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/webhooks-manage",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "action": "create",
      "name": "Meu webhook",
      "url": "https://exemplo.com/webhook",
      "events": [
        "messages",
        "message_status"
      ],
      "all_numbers": True
    },
)
print(res.status_code, res.json())

Endpoints

Integrações (Typebot & Chatwoot)

Liste e configure as integrações de automação e atendimento da conta (recursos integrations-manage para Typebot e chatwoot-integrations-manage para Chatwoot). Ambos seguem o padrão { action }:

Typebot: list, create, update, delete, test.
Chatwoot: list, create, update, delete, test, provision (cria a inbox e liga o espelhamento).

create/update recebem tokens (Typebot/Chatwoot) que vão para o cofre (Vault) e não voltam em texto. provision e enable_sync têm efeito real — confirme antes de chamar.

curl -X POST \
  "https://api.hypeai.com.br/integrations-manage" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "list"
}'

const res = await fetch(
  "https://api.hypeai.com.br/integrations-manage",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "action": "list"
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/integrations-manage",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "action": "list"
    },
)
print(res.status_code, res.json())

Precisa de uma chave ou da UI guiada? Acesse o painel. Para enviar e receber mensagens, veja a API de WhatsApp no seletor acima.

Embedded Signup as a Service

beta

API HypeAi Connect

Embuta a conexão do WhatsApp oficial dentro do seu SaaS. O seu backend chama a Connect API com umachave de agência, recebe um connect_url hospedado, e o seu cliente final conecta o WhatsApp dele em poucos cliques — sem nunca ver o painel da HypeAi. Cada cliente final vira um sub-cliente isolado da sua conta.

Começar

Visão geral

O modelo é "Stripe Connect do WhatsApp": a HypeAi é o provedor, o seu SaaS é a plataforma, e cada cliente final do seu SaaS é um sub-cliente. O fluxo, por cliente final:

1. Seu backend chama POST https://api.hypeai.com.br/connect-session com a chave de agência.
2. Recebe connect_url (página hospedada) + webhook_secret (uma vez).
3. Abre o connect_url em popup ou iframe; o cliente final autoriza na Meta.
4. Você recebe o evento connection.completed no seu webhook (a fonte de verdade) e o número já opera pela API oficial.

Acesso por convite. As chaves de escopo agência que habilitam o Connect são emitidas pela equipe (como na Coexistência). Fale com a gente para receber a sua.

Resposta de connect-session (POST)

{
  "client_id": "…",
  "session_token": "cs_…",
  "connect_url": "https://app.integra.hypeai.com.br/c/cs_…",
  "onboarding_slug": "…",
  "webhook_secret": "whsec_…",   // só na criação; guarde p/ validar o HMAC
  "capacity": { "pool": 50, "active": 12, "available": 38, "reason": "ok" },
  "pool_exhausted": false,
  "created": true
}

Começar

Autenticação

Sempre server-to-server com uma chave hai_live_ de escopo agência. A conta dona da chave é a fronteira: a HypeAi deriva a sua conta só da chave — nunca do corpo do request. Nunca exponha a chave de agência no front-end do cliente final.

Idempotência: envie um header Idempotency-Key no POST para que retries de rede devolvam a MESMA sessão (mesmo token e mesmo webhook_secret), sem provisionar de novo.

Header

Authorization: Bearer hai_live_SUA_CHAVE_DE_AGENCIA

Começar

Primeiro request

Monte a chamada e copie o código (cURL, JavaScript ou Python). O Explorer gera o código pronto para o seu backend.

Abrir o Explorer interativo no app →

Endpoints

Criar sessão de conexão

POST /connect-session provisiona (idempotente por external_customer_id) o sub-cliente do seu cliente final e devolve o connect_url + o webhook_secret (revelado uma única vez).

Campo	Tipo	Descrição
`external_customer_id`*	string	O id do cliente final no SEU sistema. É a chave de idempotência — re-chamar devolve o mesmo sub-cliente.
`customer_name`*	string	Nome do cliente final (vira o nome do workspace/sub-cliente).
`webhook_url`	string	Seu endpoint HTTPS p/ receber os eventos do número.
`events`	array	Opcional. Eventos que o webhook assina. Default: `messages`, `message_status`, `connection` (ciclo de vida: `connection.completed/failed`, `pool.exhausted`). Coexistência (opt-in — não entram no default): `smb_message_echoes` = eco das mensagens que o cliente final envia pelo app do celular (essencial p/ inbox/CRM completo); `history` e/ou `smb_app_state_sync` (PII) = histórico (180 dias) e contatos importados. P/ webhook já criado, adicione eventos via `webhooks-manage` (`action: "update"`).
`allowed_origin`	string	Origem https do seu app — valida o `postMessage` de handoff quando o `connect_url` é aberto em popup/nova aba a partir do seu app (NÃO use iframe: o Embedded Signup da Meta exige janela top-level).
`return_url`	string	Para onde redirecionar após conectar (modo popup/redirect). DEVE ter a mesma origem de `allowed_origin`.
`config.number_limit`	integer	Opcional. Teto de números do sub-cliente (1–1000).
`config.quota`	object	Opcional. Pacote de mensagens do sub-cliente: `monthly_allowance` (obrigatório), `rollover_enabled?`, `rollover_expiry_months?`, `mode?` (`enforce`\|`warn`).

A resposta traz o client_id do sub-cliente. Com ele + a sua chave de agência você configura tudo mais do cliente (quota via integra_set_quota, Typebot, Chatwoot, perfil do número e templates — o cliente final cria/edita/dispara templates de dentro do seu SaaS) passando client=<client_id> nas ferramentas de Gestão — inclusive antes de o cliente conectar. Ou passe o bloco config acima para fazer number_limit e quota na mesma chamada. No runtime REST não precisa de parâmetro nenhum: a chave de agência opera os números dos sub-clientes direto em /v1/{phone_number_id}/… (envio, mídia, tudo) — o gateway resolve o dono pelo número; GET /v1 lista o portfólio inteiro com o client_id de cada número.

Guarde o webhook_secret na resposta: ele só vem nesta chamada. Use-o para validar a assinatura X-HypeAi-Signature-256 dos eventos.

curl -X POST \
  "https://api.hypeai.com.br/connect-session" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_customer_id": "petshop-001",
  "customer_name": "Patas & Cia",
  "flow": "coexistence",
  "webhook_url": "https://seu-saas.com/webhooks/hypeai",
  "allowed_origin": "https://app.seu-saas.com",
  "return_url": "https://app.seu-saas.com/whatsapp/ok",
  "events": [
    "messages",
    "message_status",
    "connection"
  ],
  "config": {
    "connection_limit": 2,
    "quota": {
      "monthly_allowance": 1000
    }
  }
}'

const res = await fetch(
  "https://api.hypeai.com.br/connect-session",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "external_customer_id": "petshop-001",
      "customer_name": "Patas & Cia",
      "flow": "coexistence",
      "webhook_url": "https://seu-saas.com/webhooks/hypeai",
      "allowed_origin": "https://app.seu-saas.com",
      "return_url": "https://app.seu-saas.com/whatsapp/ok",
      "events": [
        "messages",
        "message_status",
        "connection"
      ],
      "config": {
        "connection_limit": 2,
        "quota": {
          "monthly_allowance": 1000
        }
      }
    }),
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.post(
    "https://api.hypeai.com.br/connect-session",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
        "Content-Type": "application/json",
    },
    json={
      "external_customer_id": "petshop-001",
      "customer_name": "Patas & Cia",
      "flow": "coexistence",
      "webhook_url": "https://seu-saas.com/webhooks/hypeai",
      "allowed_origin": "https://app.seu-saas.com",
      "return_url": "https://app.seu-saas.com/whatsapp/ok",
      "events": [
        "messages",
        "message_status",
        "connection"
      ],
      "config": {
        "connection_limit": 2,
        "quota": {
          "monthly_allowance": 1000
        }
      }
    },
)
print(res.status_code, res.json())

Endpoints

Capacidade do pool (pré-check)

GET /connect-session lê a capacidade do seu pool antes de abrir a tela, sem efeitos colaterais. Você paga pelo pool agregado; cada conexão ativa consome um slot. Pool cheio = fail-closed.

Campo	Tipo	Descrição
`capacity.pool`	number	Tamanho do pool contratado.
`capacity.active`	number	Números atualmente ativos na sua conta.
`capacity.available`	number	`pool − active`: quantas conexões novas cabem agora.
`pool_exhausted`	boolean	`true` quando `available ≤ 0` — mostre "contratar mais conexões" em vez de abrir a tela.

curl -X GET \
  "https://api.hypeai.com.br/connect-session" \
  -H "Authorization: Bearer hai_live_SEU_TOKEN"

const res = await fetch(
  "https://api.hypeai.com.br/connect-session",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer hai_live_SEU_TOKEN",
    },
  }
);
const data = await res.json();
console.log(res.status, data);

import requests

res = requests.get(
    "https://api.hypeai.com.br/connect-session",
    headers={
        "Authorization": "Bearer hai_live_SEU_TOKEN",
    },
)
print(res.status_code, res.json())

Fluxo

Página hospedada & handoff

O connect_url aponta para uma página hospedada pela HypeAi que roda o Embedded Signup da Meta (o popup roda no domínio da HypeAi — você não precisa cadastrar o seu domínio na Meta). Abra-a:

Popup / nova aba: o jeito mais simples; ao concluir, redireciona para o return_url.
Iframe: passe allowed_origin na criação; a página só embute na sua origem e envia um postMessage ao concluir.

O postMessage é conveniência de UX. A confirmação confiável de que conectou é o webhook connection.completed abaixo.

Handoff via postMessage (no seu app)

window.addEventListener("message", (e) => {
  if (e.origin !== "https://app.integra.hypeai.com.br") return;
  if (e.data?.source !== "hypeai-connect") return;
  if (e.data.event === "connection.completed") {
    // UX: o número conectou. (A fonte de verdade é o webhook server-to-server.)
  }
});

Fluxo

Eventos de conexão (webhook)

O webhook do parceiro assina o evento connection por padrão. O payload carrega o sub-evento no campoevent, assinado com HMAC-SHA256 (header X-HypeAi-Signature-256) usando o seuwebhook_secret:

connection.completed — o cliente final conectou um número; ele já opera pela API oficial.
connection.failed — a tentativa de conexão terminou em erro (troca de token / vínculo). O campo reason traz o motivo; ofereça tentar de novo.
pool.exhausted — uma tentativa de conexão bateu no limite do pool (fail-closed). Faça upsell / aumente o pool.

Valide SEMPRE a assinatura HMAC antes de confiar no evento (mesmo esquema dos webhooks de mensagem — veja a API de WhatsApp → Webhooks no seletor acima).

Evento connection.completed

POST  (seu webhook_url)
X-HypeAi-Event: connection
X-HypeAi-Signature-256: sha256=<hmac do corpo com o seu webhook_secret>

{
  "event": "connection.completed",
  "client_id": "…",
  "phone_number_id": "…",
  "display_phone_number": "+55 11 9…",
  "at": "2026-06-30T12:00:00.000Z"
}

Em breve

Trazer uma agência inteira num popup

Para parceiros com dezenas de WhatsApp (uma operação inteira de uma vez), a HypeAi tem o fluxo demigração em massa: um único consentimento na Meta enumera todas as contas WhatsApp Business concedidas, e você as organiza em sub-clientes — em vez de um popup por número. Quem é dono da conta de parceiro já o opera pelo painel (botão Migrar agência na tela de Números).

Em breve. Esse modo depende do mesmo acesso avançado da Meta (business_management) que libera a Coexistência. Está construído e atrás de um flag — assim que a Meta aprovar, ligamos. Até lá, use o fluxo de 1 número por cliente final acima (que não depende de nenhuma aprovação nova).

Precisa de uma chave de agência para o Connect? Fale com a equipe pelo painel. Para enviar mensagens depois de conectar, veja a API de WhatsApp no seletor acima.

Formatos para máquinas e IAs

openapi.json — contrato OpenAPI 3.1, importável em ferramentas de dev e IA.
llms-full.txt — referência completa em markdown, um arquivo para LLMs.
Servidor MCP — a API operável por agentes (Claude, ChatGPT etc.).