> ## 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 (ou o token da instância), tools de envio, grupos e conexão por QR, 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, Codex…) pode enviar mensagens, administrar grupos e até conectar o número pelo QR, usando as suas instâncias. 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**. Apps que não fazem OAuth podem usar o [token da instância](#sem-oauth-token-da-instancia). O MCP só **envia e consulta metadados**. Ele não lê o histórico de conversas ([D14](/concepts); as mensagens recentes guardadas no pareamento ficam só em `GET /chats/{phone}/messages` da REST). 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. ```bash theme={"system"} codex mcp add wabox --url https://mcp.wabox.me/mcp codex mcp login wabox ``` O segundo comando abre o navegador para você autorizar na tela do Wabox. 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 rodando 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: [Client-Token](/security/client-token) (se ativado) e [lista de IPs](/security/ip-allowlist). ```bash theme={"system"} claude mcp add --transport http wabox https://mcp.wabox.me/mcp \ --header "Authorization: Bearer $WABOX_INSTANCE_TOKEN" ``` ```json theme={"system"} { "mcpServers": { "wabox": { "url": "https://mcp.wabox.me/mcp", "headers": { "Authorization": "Bearer ${env:WABOX_INSTANCE_TOKEN}" } } } } ``` ```bash theme={"system"} codex mcp add wabox --url https://mcp.wabox.me/mcp --bearer-token-env-var WABOX_INSTANCE_TOKEN ``` Com Client-Token ativado, envie também o header `Client-Token` (Claude Code e Cursor aceitam vários `headers`). O token da instância fica em **Instância › Dados**; gerar um novo token derruba o acesso do app. ## A tela de autorização Ao conectar por OAuth, 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` | | `instance:connect` | `instance_qr` | O app só enxerga as tools dos escopos concedidos. `status` está sempre disponível. ## Tools | Tool | O que faz | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | Ponto de partida: quem é o app, workspace, escopos, instâncias (conexão e assinatura) e **próximos passos** (instância desconectada, trial vencido, permissão que falta). | | `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). | | `instance_qr` | O QR code de login como **imagem**, para você escanear direto no chat quando a instância cair. Inicia a sessão se for preciso; se já estiver conectada, diz isso. | | `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. ## 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." * "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](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: o app precisa passar pela autorização de novo para voltar a usar suas instâncias. Apps que usam o token da instância são desligados gerando um novo token em **Instância › Dados**. ## MCP da conta vs MCP das docs | Servidor | URL | Serve para | | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------ | | MCP da conta | `https://mcp.wabox.me/mcp` | Operar as suas instâncias: enviar, grupos, QR, status. Precisa de autorização. | | MCP das docs | `https://developer.wabox.me/mcp` | Buscar nesta documentação. Só leitura, sem login. Veja [Construir com IA](/build-with-ai). | Vale conectar os dois: o das docs ajuda o assistente a escrever a integração; 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, 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** 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, os dois valem, como na REST. * 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`.