Skip to main content
O Wabox expõe um servidor MCP em https://mcp.wabox.me/mcp. Qualquer app compatível (Claude, ChatGPT, Claude Code, Cursor, Codex…) pode ler as suas conversas, enviar mensagens, administrar grupos e conectar o número pelo QR, usando as suas instâncias. A autorização é por OAuth: numa tela do Wabox você escolhe quais instâncias e quais permissões o app terá, e pode revogar a qualquer momento em Apps conectados. Apps que não fazem OAuth podem usar o token da instância.
A leitura não é o histórico completo do WhatsApp. Ela junta as mensagens que o celular enviou no pareamento (até 50 por conversa) com as que a sessão viu desde que iniciou. Veja O que a leitura enxerga. Para reagir a mensagens recebidas em tempo real, use webhooks.

​
Conectar

  1. No claude.ai, abra Configurações › Conectores › Adicionar conector personalizado.
  2. Nome: Wabox. URL: https://mcp.wabox.me/mcp.
  3. Clique em Conectar. O Wabox abre a tela de autorização. Entre na sua conta, marque as instâncias e permissões e clique em Autorizar.
A mesma URL e os mesmos passos estão no painel, em Apps conectados › Como conectar.

​
Sem OAuth: token da instância

Para clientes que só sabem mandar um header (agentes em servidor, n8n, scripts, Codex sem navegador), o servidor também aceita o token da instância como bearer. Nesse caso o app enxerga uma instância só, com todas as permissões, e valem as mesmas proteções da API REST: a exigência de API key (se ligada) e a lista de IPs.
Se o workspace exige API key nas rotas de instância, envie também uma key com instances:operate no header Client-Token. O Authorization já está ocupado pelo token da instância, e Claude Code e Cursor aceitam vários headers:
Sem a key (ou com uma inválida), o servidor responde 401 api_key_required. Com uma key sem a permissão, responde 403 insufficient_scope. O token da instância fica em Instância › Dados, e gerar um novo token derruba o acesso do app.

​
A tela de autorização

Ao conectar por OAuth, o app redireciona você para app.wabox.me/oauth/authorize. Ali você define: Qualquer membro do workspace pode autorizar um app. Owners e admins revogam qualquer autorização; membros revogam só as próprias.

​
Permissões (escopos)

O app só enxerga as tools dos escopos concedidos. status está sempre disponível. Autorizações feitas antes de messages:read e chats:read existirem não ganham esses escopos sozinhas: para o app ler conversas, revogue e conecte de novo.

​
Tools

Todas aceitam instance_id. Ele é opcional quando o app foi autorizado para uma única instância. Com várias, o app precisa informá-lo ou chamar list_instances antes.

​
O que a leitura enxerga

read_chat e search_messages leem duas fontes e juntam o resultado:
  • Histórico do pareamento. Ao conectar, o celular envia as conversas recentes, e o Wabox guarda até 50 mensagens por conversa (o mesmo de GET /chats/{phone}/messages). Não precisa da instância conectada. Desligue em settings.history_enabled.
  • Mensagens ao vivo. As mensagens recebidas e enviadas desde que a sessão iniciou ficam na memória do servidor da sessão, nunca em disco, até 4096 por instância. Elas somem quando a sessão reinicia.
Entre as duas pode haver lacunas: mensagens de quando a sessão estava parada, ou mais antigas que as 50 do pareamento, não aparecem. A resposta traz coverage, com o que veio de cada fonte e desde quando a memória cobre, e o assistente usa isso para avisar você. Mídia vem como tipo e legenda; o arquivo só tem link quando a sessão o recebeu ao vivo. Sem phone, search_messages lê no máximo as 150 conversas do histórico gravadas mais recentemente.

​
O que acontece num envio

Antes de enfileirar, a tool confere se a instância está conectada, se a assinatura ou o trial está ativo e se o número existe no WhatsApp. Os erros voltam com o mesmo code da API REST (instance_not_connected, phone_not_on_whatsapp, subscription_required, rate_limited…), então o assistente consegue explicar o que faltou. Sucesso significa enfileirado: a entrega real chega no webhook delivery, com o mesmo message_id que a tool devolveu. Os envios passam pela mesma fila, pelo mesmo pacing anti-ban e pelo mesmo rate limit da API.

​
Exemplos de pedidos

Depois de conectar, peça ao assistente em linguagem natural:
  • “Use o Wabox para ver o status da minha instância e me dizer o que falta.”
  • “Quais conversas do meu WhatsApp estão sem resposta? Resuma cada uma em uma linha.”
  • “Resuma o que falaram hoje no grupo Equipe.”
  • “Procure no meu WhatsApp a mensagem em que falaram do orçamento da reforma.”
  • “Meu número caiu. Pegue o QR do Wabox e me mostre para eu escanear.”
  • “Mande pelo Wabox ‘Seu pedido saiu para entrega’ para o 5511988887777.”
  • “Crie um grupo ‘Suporte Loja’ no Wabox com 5511988887777 e 5511977776666 e coloque o primeiro como admin.”
  • “Envie para o grupo 120363012345678901-group a imagem https://exemplo.com/promo.png com a legenda ‘Promoção de hoje’.”

​
Revogar

Em Apps conectados (menu lateral, ou na aba da instância) cada autorização mostra o app, as instâncias, os escopos, quem autorizou e o último uso. Revogar corta o acesso na hora, e o app precisa passar pela autorização de novo para voltar a usar suas instâncias. Para desligar apps que usam o token da instância, gere um novo token em Instância › Dados.

​
MCP da conta vs MCP das docs

Você pode conectar os dois. O das docs ajuda o assistente a escrever a integração, e o da conta deixa ele operar o número.

​
Segurança

  • Por OAuth, o app nunca recebe o token da instância. Ele recebe tokens próprios, curtos (1 h) e renováveis, que o Wabox guarda hasheados. Reusar um token de renovação já usado revoga a autorização inteira.
  • A exigência de API key e a lista de IPs não se aplicam a apps autorizados por OAuth. Os apps de IA rodam na nuvem do fornecedor, com IPs que mudam, e a autorização já é uma credencial individual e revogável. Com o token da instância como bearer, as duas valem, como na REST (a key vai no header Client-Token).
  • Para quem desenvolve apps, o servidor segue a spec de autorização do MCP com registro dinâmico de clientes (RFC 7591), Client ID Metadata Documents, PKCE S256 obrigatório e metadados em /.well-known/oauth-authorization-server e /.well-known/oauth-protected-resource.