# WhatsConverte > Plataforma brasileira de WhatsApp para empresas: disparo de campanhas com agendamento, inbox, contatos e páginas de captura, com créditos pré-pagos (1 mensagem = 1 crédito). Este arquivo explica como um agente de IA ou um sistema externo integra pela API REST v1 ou pelo servidor MCP. Base da API: `https://whatsconverte.com.br/api/v1` · Servidor MCP: `https://whatsconverte.com.br/api/v1/mcp` · Documentação completa: https://whatsconverte.com.br/docs ## Acesso - Somente clientes com conta ativa. O token é criado no painel em **API & docs** (https://whatsconverte.com.br/settings/api-tokens), aparece uma única vez e é guardado por nós só como hash SHA-256. - Formato: `mkt_` + 32 caracteres hexadecimais. Envie em todas as chamadas: `Authorization: Bearer mkt_...` - Escopos: `read` (consultas) e `send` (enviar mensagens e gravar contatos). Dê a cada integração só o que ela precisa. - Limite por token: 60 requisições por minuto por padrão (configurável de 10 a 600). Cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` em todas as respostas; ao passar do limite, 429. - Use a API só de servidor para servidor. Nunca coloque o token em front-end, app móvel ou repositório. Revogue e gere outro se vazar. ## Servidor MCP - Endereço: `https://whatsconverte.com.br/api/v1/mcp`, transporte Streamable HTTP, respostas em JSON, sem sessão. - Autenticação: cabeçalho `Authorization: Bearer mkt_...` (o mesmo token da API). O escopo é conferido por ferramenta. - Claude Code: `claude mcp add --transport http whatsconverte https://whatsconverte.com.br/api/v1/mcp --header "Authorization: Bearer mkt_SEU_TOKEN"` - Claude Desktop (claude_desktop_config.json), pelo adaptador mcp-remote: ``` {"mcpServers": {"whatsconverte": {"command": "npx", "args": ["-y", "mcp-remote", "https://whatsconverte.com.br/api/v1/mcp", "--header", "Authorization:${WC_TOKEN}"], "env": {"WC_TOKEN": "Bearer mkt_SEU_TOKEN"}}}} ``` - Cursor (~/.cursor/mcp.json): `{"mcpServers": {"whatsconverte": {"url": "https://whatsconverte.com.br/api/v1/mcp", "headers": {"Authorization": "Bearer mkt_SEU_TOKEN"}}}}` - VS Code (.vscode/mcp.json): `{"servers": {"whatsconverte": {"type": "http", "url": "https://whatsconverte.com.br/api/v1/mcp", "headers": {"Authorization": "Bearer mkt_SEU_TOKEN"}}}}` Ferramentas: - `conta_resumo()` [read]: empresa, fuso, saldo de créditos, renovação dos créditos grátis e escopos do token. - `listar_numeros()` [read]: números de WhatsApp da conta com status. Só `CONNECTED` envia. - `consultar_contato(phone)` [read]: dados do contato; `optOutAt` preenchido = não pode receber. - `salvar_contato(phone, name?, attributes?)` [send]: cria ou atualiza pelo telefone. Não cobra. - `enviar_mensagem(to, type?, text?, mediaUrl?, caption?, fileName?, variables?, instanceId?, idempotencyKey?)` [send]: envia 1 mensagem e cobra 1 crédito. - `consultar_mensagem(id)` [read]: status da mensagem enviada. Regras para agentes: 1. Nunca envie sem o usuário confirmar destinatário e texto. Uma mensagem por chamada; não existe envio em massa pela API (campanhas são feitas no painel). 2. Sempre passe `idempotencyKey` (um UUID) em `enviar_mensagem` e reutilize a mesma chave ao repetir a chamada: a mensagem não sai nem é cobrada duas vezes. 3. Antes de enviar, confira saldo (`conta_resumo`) e se há número conectado (`listar_numeros`). 4. O envio é assíncrono: a resposta vem com `status: "queued"`. Acompanhe com `consultar_mensagem`. 5. LGPD: envie só para quem autorizou o contato. Quem responde PARAR, SAIR, CANCELAR ou STOP vira opt-out automaticamente e qualquer envio para essa pessoa é recusado (409 `contact_opted_out`), sem cobrança. ## API REST Respostas de sucesso: `{"data": {...}}`. Erros: `{"error": {"code": "...", "message": "...", "details": ...}}`. - `GET /me` [read]: conta e escopos do token. - `GET /credits` [read]: `{"balance": 142, "freeCreditsResetAt": "..."}` - `GET /instances` [read]: números de WhatsApp (`id`, `provider` EVOLUTION ou META_CLOUD, `phone`, `displayName`, `status`, `dailyCap`, `lastConnectedAt`). - `POST /messages` [send]: envia uma mensagem. Responde 202. - `GET /messages/{id}` [read]: status da mensagem. - `GET /contacts?phone=11984134029` [read]: consulta um contato. - `POST /contacts` [send]: cria ou atualiza contato. Responde 201. Exemplo de envio: ``` curl https://whatsconverte.com.br/api/v1/messages \ -H "Authorization: Bearer mkt_SEU_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \ -d '{"to": "11984134029", "type": "text", "text": "Olá {{nome}}!", "variables": {"nome": "Paulo"}}' ``` Resposta: `{"data": {"id": "cm...", "status": "queued", "to": "5511984134029", "instanceId": "cm...", "type": "text", "creditsCharged": 1, "creditsRemaining": 141}}` Campos de `POST /messages`: - `to` (obrigatório): DDD + número (10 ou 11 dígitos, recebe 55) ou DDI completo (12 a 15 dígitos). - `type`: `text` (padrão), `image`, `video`, `document` ou `audio`. - `text`: até 4096 caracteres, obrigatório em `text`. Aceita variáveis `{{nome}}` e spintax `{oi|olá}`. - `mediaUrl`: obrigatório fora de `text`. Precisa ser `https://` em endereço público (sem IP privado, localhost ou porta diferente de 443). - `caption` (até 1024), `fileName` (até 200), `variables` (texto até 500 por chave). - `instanceId`: número que envia; padrão é o primeiro conectado. - Cabeçalho `Idempotency-Key`: 8 a 128 caracteres `[A-Za-z0-9._:-]`. A chave vale para sempre na conta: repetir devolve a mensagem original com `"idempotent": true`. Ordem das verificações (nada é cobrado se falhar antes do passo 6): 1) token e escopo; 2) limite por minuto; 3) payload; 4) opt-out do contato; 5) número conectado e número existente no WhatsApp; 6) débito de 1 crédito; 7) fila de envio. Status: `queued` → `sent` → `delivered` → `read`, ou `failed` (com `errorMsg`). Uma mensagem `failed` devolve o crédito. O status só avança, nunca volta. A API envia na hora: a janela de horário e o limite diário por número valem para campanhas do painel, não para a API. Não há webhook de status para clientes; consulte `GET /messages/{id}`. ## Erros - 400: `validation_error`, `invalid_json`, `invalid_phone`, `invalid_whatsapp_number` (não cobra), `invalid_media_url`, `invalid_idempotency_key` - 401: `missing_authorization`, `invalid_token`, `token_revoked` - 402: `insufficient_credits` (recarregue em https://whatsconverte.com.br/billing) - 403: `insufficient_scope` - 404: `not_found` - 409: `no_connected_instance`, `contact_opted_out` (não cobra) - 429: `rate_limit_exceeded` (aguarde até `X-RateLimit-Reset`) ## Créditos 1 mensagem enviada = 1 crédito. Toda conta recebe 10 créditos grátis por mês. Recarga por PIX ou cartão (Mercado Pago) em https://whatsconverte.com.br/billing. Atenção: no dia 1 de cada mês o saldo volta para os 10 créditos grátis. ## Documentação - [Documentação da API](https://whatsconverte.com.br/docs): referência completa, segurança e exemplos.