> ## Documentation Index > Fetch the complete documentation index at: https://developer.wabox.me/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Wabox é uma API não-oficial de WhatsApp (aparelho vinculado). Tudo é snake_case; a base é https://api.wabox.me/instances/{instance_id}/token/{token}. > Envios respondem { id, message_id, wabox_id, status: "queued" } na hora; o resultado real chega no webhook delivery. Envios não são idempotentes: confira GET /queue antes de repetir. > Sempre verifique X-Wabox-Signature (HMAC-SHA256 de ".") nos webhooks e deduplique por event_id. > Botões, listas, carrossel e catálogo são best effort e não renderizam no WhatsApp Web/Desktop. Não existem: chamadas, listas de transmissão, histórico de mensagens, instância mobile. > Não invente endpoints ou campos: use o OpenAPI em https://api.wabox.me/openapi.json. # Claude, ChatGPT e outros apps de IA (MCP) > Conecte um assistente de IA ao seu número pelo servidor MCP do Wabox: OAuth com escolha de instâncias e permissões, tools de envio e de grupos, e como revogar. O Wabox expõe um servidor [MCP](https://modelcontextprotocol.io) em `https://mcp.wabox.me/mcp`. Qualquer app compatível (Claude, ChatGPT, Claude Code, Cursor…) pode enviar mensagens e administrar grupos pelas suas instâncias, sem token na mão do app: a autorização é por **OAuth**, você escolhe **quais instâncias** e **quais permissões** numa tela do Wabox, e pode revogar a qualquer momento em **Apps conectados**. O MCP só **envia e consulta metadados**. Ele não lê o histórico de conversas: o Wabox não guarda o conteúdo das mensagens ([D14](/concepts)). Para reagir a mensagens recebidas, use [webhooks](/webhooks/overview). ## 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**. 1. Em **Configurações › Conectores**, ative o modo desenvolvedor e clique em **Criar**. 2. Nome: `Wabox`. URL: `https://mcp.wabox.me/mcp`. Autenticação: **OAuth**. 3. Clique em **Criar** e autorize na tela do Wabox. ```bash theme={"system"} claude mcp add --transport http wabox https://mcp.wabox.me/mcp ``` Depois, dentro do Claude Code, rode `/mcp`, escolha **wabox** e conclua a autorização no navegador. Em `~/.cursor/mcp.json` (ou `.cursor/mcp.json` do projeto): ```json theme={"system"} { "mcpServers": { "wabox": { "url": "https://mcp.wabox.me/mcp" } } } ``` Em **Settings › MCP**, clique em **wabox** para autenticar. A mesma URL e os mesmos passos estão no painel, em **Apps conectados › Como conectar**. ## A tela de autorização Ao conectar, o app é enviado para `app.wabox.me/oauth/authorize`. Ali você define: | Campo | O que significa | | ---------- | --------------------------------------------------------------------------- | | Workspace | Só aparece se você participa de mais de um. | | Instâncias | O app só poderá usar as marcadas. Com uma instância só, ela já vem marcada. | | Permissões | As que o app pediu; desmarque o que ele não deve poder fazer. | Qualquer membro do workspace pode autorizar um app. Owners e admins podem revogar qualquer autorização; membros, só as próprias. ### Permissões (escopos) | Escopo | Libera | | --------------- | ---------------------------------------------------------------------------------------------------------------- | | `messages:send` | `send_text`, `send_image`, `send_audio`, `send_video` | | `groups:read` | `group_metadata` | | `groups:write` | `group_create`, `group_add_participants`, `group_remove_participants`, `group_add_admins`, `group_remove_admins` | | `instance:read` | `list_instances`, `get_instance` | O app só enxerga as tools dos escopos concedidos. ## Tools | Tool | O que faz | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | `list_instances` | Instâncias que o app pode usar: id, nome, número, status. | | `get_instance` | Status ao vivo de uma instância (conectada, celular alcançável, assinatura). | | `send_text` | Texto para um número ou grupo, com resposta (citação) opcional. | | `send_image` / `send_video` | Mídia por **URL pública**, com legenda opcional. | | `send_audio` | Áudio por URL. Vai como nota de voz por padrão (`as_voice_note: false` manda como arquivo). | | `group_create` | Cria um grupo com participantes; a instância entra como admin. | | `group_metadata` | Nome, descrição, participantes e admins. | | `group_add_participants` / `group_remove_participants` | Adiciona ou remove números. | | `group_add_admins` / `group_remove_admins` | Promove ou rebaixa participantes. | Todas aceitam `instance_id`. Ele é opcional quando o app foi autorizado para uma única instância; com várias, o app precisa informar (ou chamar `list_instances` antes). ### O que acontece num envio Antes de enfileirar, a tool confere que a instância está **conectada**, que a assinatura ou trial está ativa e que o número **existe no WhatsApp**. 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. O sucesso significa **enfileirado**: a entrega real chega no webhook [`delivery`](/webhooks/delivery), com o mesmo `message_id` que a tool devolveu. Os envios passam pela mesma fila, pacing anti-ban e [rate limit](/guides/rate-limits-and-errors) da API. ## 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: o app precisa passar pela autorização de novo para voltar a usar suas instâncias. ## Segurança * O app nunca recebe o token da instância. Ele recebe tokens OAuth próprios, curtos (1 h) e renováveis, guardados hasheados. Reuso de um token de renovação já usado revoga a autorização inteira. * [Client-Token](/security/client-token) e [lista de IPs](/security/ip-allowlist) **não se aplicam** ao MCP: os apps de IA rodam na nuvem do fornecedor, com IPs que mudam, e a autorização OAuth já é uma credencial individual e revogável. * Para desenvolvedores de apps: o servidor segue a [spec de autorização do MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization) com registro dinâmico de clientes (RFC 7591), Client ID Metadata Documents, PKCE S256 obrigatório e metadata em `/.well-known/oauth-authorization-server` e `/.well-known/oauth-protected-resource`.