Como se conectar à API e ao servidor MCP da WACRM

A Core API da WACRM (api.wacrm.ai/v1) é a mesma API documentada por completo no portal do desenvolvedor, e o wacrm-mcp é um pequeno servidor que envolve cinco dessas chamadas como ferramentas para um agente de IA compatível com MCP. A Core API funciona hoje; o wacrm-mcp ainda não é distribuído como pacote instalável, e mesmo quando for, há uma lacuna real que vale conhecer antes de começar: a tela de criação de keys do Workspace só oferece sua lista de escopos original, então vários dos escopos mais novos, próprios da WACRM — incluindo todo escopo que as próprias ferramentas do wacrm-mcp precisam — ainda não podem ser selecionados ali. Este tutorial se limita às chamadas que realmente funcionam com uma key criada hoje, e diz claramente onde o resto para por enquanto.

O que você precisa antes de começar

• Uma conta WACRM Workspace com pelo menos um projeto (acesso antecipado — veja preços se ainda não tiver um).
• curl, ou qualquer cliente HTTP que consiga definir um header — nada mais para instalar na parte da API.

Crie uma API key e faça sua primeira chamada

1. Crie uma API key. No Workspace, abra Developer / API & MCP e crie uma nova key. Escolha Secret key (sk_live_…) — server-side para um servidor ou script, ou Publishable key (pk_live_…) — browser-safe se a key for usada em código de navegador, e dê a ela um rótulo que você reconheça depois. Deixe “Restrict what this key can do (advanced)” desligado por enquanto — os escopos padrão dela já cobrem as duas chamadas abaixo. A nova key é mostrada exatamente uma vez, em um diálogo “Your new API key” logo depois de criá-la, que avisa que a WACRM a guarda com hash e não pode reenviá-la nem recuperá-la — copie-a imediatamente. Essa mesma tela Developer também mostra um card de MCP marcado “Preview” — não é um conector funcional ainda, só uma prévia do que vem por aí assim que o wacrm-mcp for lançado; mais abaixo, “Conecte o servidor MCP” explica o que esperar.

   O portal do desenvolvedor documenta a mesma Core API que essa key chama — autenticação, escopos, idempotência e a referência completa de endpoints:

   

2. Chame o health check — sem precisar de key. GET /v1/health é público: é a forma mais rápida de confirmar que você consegue alcançar a API antes de se preocupar com autenticação.

   Code Copy

   curl -s https://api.wacrm.ai/v1/health

   Code Copy

   {"status":"ok","version":"1.0.0","database":"ok"}

   

3. Faça sua primeira chamada autenticada. Toda requisição autenticada envia a key como header Authorization: Bearer. GET /v1/message-templates lista os templates de mensagem do WhatsApp do seu projeto e só precisa de templates:read, que vem ativado por padrão tanto numa Secret key quanto numa Publishable key — então a key do passo 1 já funciona aqui sem pedir nenhum escopo extra.

   Code Copy

   curl -s https://api.wacrm.ai/v1/message-templates \
     -H "Authorization: Bearer sk_live_your_scoped_key"

   Code Copy

   {
     "data": [
       {
         "id": "7e9b9b7a-2f3a-4e36-9a0d-6a2b7a9b7a01",
         "name": "order_confirmation",
         "language": "en",
         "category": "utility",
         "body": "Hi {{1}}, your order #{{2}} is confirmed.",
         "status": "approved",
         "created_at": "2026-10-20T09:00:00+00:00",
         "variant_group_id": null
       }
     ]
   }

Quais chamadas da API da WACRM eu posso fazer hoje?

Toda rota v1 da WACRM verifica o escopo exigido em cada requisição, e a tela de criação de keys do Workspace ainda não oferece vários escopos — então a resposta honesta depende do endpoint, não do seu plano:

Limites de taxa e novas tentativas

Dois limites estão documentados hoje: os endpoints de IA (/v1/ai/*) têm limite de taxa, e POST /v1/messages está limitado a 30 requisições por minuto por key — ambos respondem 429 ao serem atingidos. Uma escrita que nunca deveria rodar duas vezes, como POST /v1/messages, também aceita um header Idempotency-Key: repetir a mesma requisição com a mesma key reproduz a primeira resposta em vez de enviar de novo, que é a forma segura de tentar de novo depois de um timeout ou uma conexão perdida.

Conecte o servidor MCP a um agente de IA

O wacrm-mcp ainda não é algo que um cliente WACRM consiga instalar hoje. O pacote vive só dentro do repositório privado da WACRM — não há pacote npm nem repositório público no GitHub para apontar — e um lançamento público está planejado, sem data definida ainda. O que vem a seguir é o formato que seu cliente MCP vai usar assim que o wacrm-mcp for lançado, não um conector que você possa executar agora.

Aponte seu cliente MCP para o servidor via stdio, com sua própria key com escopos no ambiente — o mesmo formato de key do passo 1 acima:

{
  "mcpServers": {
    "wacrm": {
      "command": "node",
      "args": ["/path/to/apps/mcp/src/index.mjs"],
      "env": {
        "WACRM_API_KEY": "sk_live_your_scoped_key",
        "WACRM_API_BASE": "https://api.wacrm.ai"
      }
    }
  }
}

WACRM_API_KEY é a única variável que o wacrm-mcp exige — a mesma key com escopos do passo 1, enviada só como header Authorization: Bearer e nunca registrada em log nem devolvida no resultado de uma ferramenta. WACRM_API_BASE tem como padrão https://api.wacrm.ai e só precisa ser definida para apontar a um sandbox ou uma simulação local. Uma key de conta (sk_acc_live_...) também precisa de WACRM_PROJECT_ID, enviada como X-WACRM-Project-Id; uma key de projeto (sk_live_...) já implica o projeto dela e não precisa disso.

Assim que estiver em funcionamento, uma chamada tools/list vai retornar as cinco ferramentas — send_template, read_conversation, create_contact, notify_order e wallet_balance — descritas por completo na página do wacrm-mcp.

Pronto para testar isso no seu próprio projeto? Solicite acesso antecipado para conseguir um Workspace, ou veja preços primeiro se ainda estiver comparando planos. Para mais guias como este, explore a lista completa de guias.