API REST e GraphQL

A WhatsWave expõe duas superfícies para integração técnica: a API REST (recomendada para a maioria das ações) e o GraphQL (focado em leitura e dados em tempo real). Ambas usam o mesmo token de integração gerado no painel.

Quando usar cada uma

Use REST para ações e integrações (ERP, CRM próprio, n8n, backend). Use GraphQL quando precisar de atualização ao vivo dos mesmos dados que o dashboard já acompanha — não como substituto geral da REST.

A documentação interativa (Swagger) da API REST fica em service.whatswave.com.br/docs. Página de produto: /recursos/api-rest-graphql.

Como obter o token de integração

1. Entre no app em Configurações → Chaves de API
2. Na seção Integração, gere ou copie o token de integração
3. Envie nas requisições como Bearer:

Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO

O token vale para REST e GraphQL. Guarde-o com segurança — quem tiver o token age em nome da sua empresa, dentro das permissões do plano.

Planos sem acesso à API (por exemplo Free/Light, conforme o catálogo) não liberam o token. Faça upgrade se a opção estiver bloqueada.

API REST — cobertura completa

A REST é a API completa do produto: a maior parte do que você faz no painel pode ser automatizada por endpoints NestJS.

Base de produção: https://api.whatswave.com.br (ou https://service.whatswave.com.br).

Exemplos do que a REST cobre

• Instâncias / canais — status, conexão, metadados de números WhatsApp e Instagram
• Mensagens e conversas — envio, histórico, filas
• Contatos — criação, atualização, tags, importação
• Campanhas — criar, agendar, acompanhar disparos
• CRM — boards, cards, movimentação no funil
• Agentes de IA — configuração e execução assistida via API
• Workflows — disparos e integrações com o motor de automações
• Webhooks — receber eventos externos e conectar ferramentas
• Billing / conta — operações expostas na documentação Swagger (conforme seu papel e plano)

Consulte sempre o Swagger para paths, payloads (snake_case) e códigos de erro atuais.

Exemplo rápido (REST)

curl -s https://api.whatswave.com.br/health \
  -H "Authorization: Bearer SEU_TOKEN"

Para endpoints autenticados da sua empresa, use o mesmo header Bearer e os paths listados em /docs.

GraphQL — dados e tempo real

Endpoint: https://api.whatswave.com.br/v1/graphql
WebSocket (subscriptions): wss://api.whatswave.com.br/v1/graphql

O GraphQL da WhatsWave (Hasura) serve principalmente para:

1. Queries — ler dados da empresa com o mesmo modelo do dashboard
2. Subscriptions — receber atualizações em tempo real quando o banco muda

Ele não substitui a REST para enviar mensagem, criar campanha ou executar regras de negócio complexas. Para isso, continue na API REST.

O que você pode acompanhar em tempo real (GraphQL)

Subscriptions e leituras típicas (sempre filtradas pela sua empresa / permissões):

Use o protocolo graphql-ws (como o dashboard) com o mesmo Bearer token na conexão.

Limite de conexões WebSocket

Há um limite de conexões WebSocket simultâneas que sua conta pode manter no GraphQL em tempo real.

Boas práticas:

• Prefira uma conexão por aplicação e várias subscriptions nela
• Não abra dezenas de clientes WS em paralelo (scripts, workers e abas extras somam no limite)
• Feche conexões ociosas
• Se precisar de mais capacidade para um volume alto de listeners, fale com o suporte ou avalie um plano superior

Exceder o limite pode fazer novas conexões falharem ou cair até liberar slots.

REST vs GraphQL — resumo prático

Próximos passos

• Visão geral das integrações
• Como usar webhooks recebidos
• Como integrar com n8n
• Como integrar com Zapier
• Página de recurso: API REST e GraphQL
• Swagger: Documentação da API