WhatsConverte API

Início rápido

1. Conecte pelo menos um número em Instâncias e confira se ele aparece como conectado.
2. Gere um token em API & docs com o escopo send (e read para consultar status).
3. Envie a primeira mensagem:

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"}}'

Autenticação e escopos

Todas as chamadas levam o token no cabeçalho:

Authorization: Bearer mkt_<32 caracteres hexadecimais>

O token aparece uma única vez, na criação. Guardamos só o hash SHA-256: ninguém, nem o suporte, consegue recuperá-lo. Se perder, gere outro e revogue o antigo. A revogação vale na hora.

Segurança

O que a plataforma faz

• Tráfego só por HTTPS, com HSTS.
• Tokens guardados como hash SHA-256, com escopo e limite por minuto próprios. O último uso de cada token fica visível no painel.
• Cada token só enxerga os dados da própria conta; recursos de outra conta respondem 404.
• Opt-out automático: quem responde PARAR, SAIR, CANCELAR, STOP ou "não quero mais" deixa de receber, inclusive pela API (409 contact_opted_out).
• O número é verificado no WhatsApp antes da cobrança (números conectados por QR Code). Número inexistente não cobra.
• mediaUrl só aceita https em endereço público, para impedir que a API seja usada para acessar redes internas.
• Cada envio pela API fica no registro de auditoria da conta, com o prefixo do token que enviou.
• As credenciais da Meta Cloud API dos seus números são guardadas cifradas (AES-256-GCM).

O que você deve fazer

• Chame a API só do seu servidor. Nunca coloque o token em front-end, app móvel, planilha ou repositório.
• Guarde o token em variável de ambiente ou cofre de segredos.
• Use um token por integração, com o menor escopo possível (só read para painéis e relatórios).
• Revogue tokens sem uso e troque-os periodicamente. Se um token vazar, revogue imediatamente.
• Use Idempotency-Key em todo envio, para que repetições de rede não dupliquem mensagens nem cobranças.
• Envie só para quem autorizou o contato (LGPD) e respeite os pedidos de saída.

Limites e regras de envio

Toda resposta traz:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1761350400

Ao passar do limite a resposta é 429 rate_limit_exceeded. Aguarde até X-RateLimit-Reset (unix epoch, em segundos).

Idempotência

Em POST /messages, envie um identificador único no cabeçalho Idempotency-Key (8 a 128 caracteres [A-Za-z0-9._:-]; recomendamos um UUID v4). Se a mesma chave for enviada de novo, a API devolve a mensagem original com "idempotent": true, sem enviar nem cobrar outra vez, inclusive em chamadas simultâneas.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

A chave vale para sempre dentro da conta: não reutilize a mesma chave para mensagens diferentes.

Formato das respostas

// sucesso
{ "data": { ... } }

// erro
{ "error": { "code": "insufficient_credits", "message": "Saldo insuficiente...", "details": { ... } } }

Erros

GET /me

Conta dona do token, saldo e escopos. Escopo: read.

curl -H 'Authorization: Bearer mkt_SEU_TOKEN' https://whatsconverte.com.br/api/v1/me

{
  "data": {
    "tenant": {
      "id": "cm...",
      "name": "Star Consulting",
      "slug": "star-abc123",
      "timezone": "America/Sao_Paulo",
      "credits": 142,
      "freeCreditsResetAt": "2026-11-01T03:00:00.000Z"
    },
    "token": { "scopes": ["read", "send"], "rateLimit": 60 }
  }
}

GET /credits

Saldo atual. Escopo: read.

{ "data": { "balance": 142, "freeCreditsResetAt": "2026-11-01T03:00:00.000Z" } }

GET /instances

Todos os números de WhatsApp da conta, com status. Só os CONNECTED enviam. Escopo: read.

{
  "data": {
    "instances": [
      {
        "id": "cm...",
        "provider": "EVOLUTION",          // EVOLUTION (QR Code) ou META_CLOUD (API oficial)
        "evoInstanceName": "mkt_xyz_abc",
        "phone": "5511936209286",
        "displayName": "Star Consulting",
        "status": "CONNECTED",            // CREATED | CONNECTING | CONNECTED | DISCONNECTED | ERROR
        "dailyCap": 50,
        "lastConnectedAt": "2026-10-24T12:00:00.000Z"
      }
    ]
  }
}

POST /messages

Enfileira uma mensagem e cobra 1 crédito. Responde 202; o envio acontece em segundos. Escopo: send.

Body

{
  "to": "11984134029",                // obrigatório. 10-11 dígitos recebem +55; 12-15 = DDI explícito
  "type": "text",                     // text (padrão) | image | video | document | audio
  "text": "Olá {{nome}}, tudo bem?",  // obrigatório se type=text. Aceita spintax {oi|olá}
  "mediaUrl": "https://...",          // obrigatório se type != text. https público
  "caption": "Legenda da mídia",      // opcional
  "fileName": "proposta.pdf",         // opcional, recomendado para document
  "variables": { "nome": "Paulo" },   // substitui {{nome}} ou {nome} no text/caption
  "instanceId": "cm..."               // opcional. Padrão: o primeiro número conectado
}

Ordem das verificações

Nada é cobrado se a chamada parar antes do passo 6:

1. Token, escopo send e limite por minuto.
2. Formato do payload, da mídia e da Idempotency-Key.
3. Chave de idempotência já usada → devolve a mensagem original.
4. Contato em opt-out → 409 contact_opted_out.
5. Número conectado disponível e destinatário existente no WhatsApp.
6. Débito de 1 crédito → 402 se o saldo estiver zerado.
7. Mensagem enfileirada → 202.

Resposta 202

{
  "data": {
    "id": "cm...",
    "status": "queued",
    "to": "5511984134029",
    "instanceId": "cm...",
    "type": "text",
    "creditsCharged": 1,
    "creditsRemaining": 141
  }
}

GET /messages/:id

Status atual da mensagem. Escopo: read.

curl -H 'Authorization: Bearer mkt_SEU_TOKEN' https://whatsconverte.com.br/api/v1/messages/cm...

{
  "data": {
    "message": {
      "id": "cm...", "to": "5511984134029", "type": "text", "status": "delivered",
      "instanceId": "cm...", "evoMessageId": "3EB0...",
      "sentAt": "...", "deliveredAt": "...", "readAt": null,
      "errorMsg": null, "createdAt": "..."
    }
  }
}

O status só avança (queued → sent → delivered → read). Não há webhook de status para clientes: consulte este endpoint, com intervalo de alguns segundos, até chegar ao status que você precisa.

Contatos

POST /contacts

Cria o contato ou atualiza nome e atributos se o telefone já existir. Não envia mensagem e não cobra. Escopo: send. Responde 201.

curl https://whatsconverte.com.br/api/v1/contacts \
  -H 'Authorization: Bearer mkt_SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"11984134029","name":"Paulo","attributes":{"empresa":"Star","cidade":"Campinas"}}'

Até 50 atributos, cada valor com até 500 caracteres. Os atributos ficam disponíveis como variáveis nos templates.

GET /contacts?phone=

Consulta um contato pelo telefone. Útil para checar o opt-out antes de enviar: se optOutAt estiver preenchido, o envio será recusado. Escopo: read.

curl -H 'Authorization: Bearer mkt_SEU_TOKEN' 'https://whatsconverte.com.br/api/v1/contacts?phone=11984134029'

{ "data": { "contact": { "id": "cm...", "phoneE164": "5511984134029", "name": "Paulo", "optOutAt": null, "source": "api", "createdAt": "..." } } }

Servidor MCP

Para usar o WhatsConverte em agentes de IA (Claude, Cursor, VS Code e outros clientes MCP). Transporte Streamable HTTP, respostas em JSON e sem sessão. Usa o mesmo token da API; cada ferramenta exige o seu escopo.

Endereço: https://whatsconverte.com.br/api/v1/mcp
Cabeçalho: Authorization: Bearer mkt_SEU_TOKEN

Configuração

# Claude Code
claude mcp add --transport http whatsconverte https://whatsconverte.com.br/api/v1/mcp \
  --header "Authorization: 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" } } } }

# Claude Desktop (claude_desktop_config.json), via 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" } } } }

Ferramentas

As ferramentas seguem exatamente as mesmas regras da API REST: mesmas validações, opt-out, cobrança e limite por minuto. O agente é orientado a confirmar destinatário e texto com você antes de enviar.

llms.txt

Um resumo desta documentação em Markdown, pensado para agentes de IA e LLMs, está em https://whatsconverte.com.br/llms.txt. Ele traz autenticação, ferramentas MCP, endpoints, regras de envio e erros.

Mudanças

• Outubro de 2026: servidor MCP e llms.txt; GET /contacts?phone=; campo provider em /instances; envio para contato em opt-out recusado (409 contact_opted_out); mediaUrl só https público (invalid_media_url); validação da Idempotency-Key e proteção contra chamadas simultâneas com a mesma chave; status das mensagens não regride mais.