API Reference

Documentação completa da API REST. Integre seu WhatsApp com qualquer aplicação.

Autenticação

Todas as requisições devem incluir o header X-API-Key com sua API key:

curl -X GET "https://sua-instancia.zmcp.me/api/v1/status" \
  -H "X-API-Key: zmcp_sua_api_key_aqui"

Obtendo sua API key

Acesse o dashboard da sua instância, vá na aba Conectar e crie sua API key. Cada instância tem sua própria chave. Mantenha-a em segurança.

Base URL

Cada instância tem sua própria URL. Você encontra no dashboard:

https://sua-instancia.zmcp.me

Endpoints

GET/api/v1/status

Verifica o status da conexão WhatsApp

Response:

{
  "whatsapp_connected": true,
  "phone": "+5511999999999",
  "uptime": "2d 5h 30m"
}
POST/api/v1/messages

Envia uma mensagem de texto

Request Body:

{
  "to": "+5511999999999",
  "text": "Olá! Esta é uma mensagem de teste."
}

Response:

{
  "success": true,
  "message_id": "msg_abc123",
  "timestamp": 1703894400
}
GET/api/v1/messages

Lista mensagens recentes

Query Parameters:

chat_idID do chat (opcional)
limitQuantidade máxima (default: 50)
sinceData inicial (ISO 8601)

Response:

{
  "messages": [
    {
      "id": "msg_abc123",
      "chat_id": "5511888888888@s.whatsapp.net",
      "from": "+5511888888888",
      "text": "Olá!",
      "timestamp": 1703894400,
      "is_from_me": false
    }
  ],
  "count": 1
}
GET/api/v1/contacts

Busca contatos

Query Parameters:

qTermo de busca (nome ou telefone)
limitQuantidade máxima (default: 20)

Response:

{
  "contacts": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "name": "João Silva",
      "phone": "+5511999999999",
      "is_group": false
    }
  ]
}
GET/api/v1/chats/{chat_id}/history

Histórico completo de um chat

Query Parameters:

limitQuantidade máxima (default: 100)

Response:

{
  "chat_id": "5511999999999@s.whatsapp.net",
  "messages": [
    {
      "id": "msg_abc123",
      "text": "Olá!",
      "timestamp": 1703894400,
      "is_from_me": false
    }
  ],
  "count": 50
}

Exemplos

cURL

curl -X POST "https://sua-instancia.zmcp.me/api/v1/messages" \
  -H "X-API-Key: zmcp_sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999999999",
    "text": "Olá! Mensagem enviada via API."
  }'

Python

import requests

API_URL = "https://sua-instancia.zmcp.me"
API_KEY = "zmcp_sua_api_key_aqui"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Enviar mensagem
response = requests.post(
    f"{API_URL}/api/v1/messages",
    headers=headers,
    json={
        "to": "+5511999999999",
        "text": "Olá via Python!"
    }
)

print(response.json())

Node.js

const API_URL = "https://sua-instancia.zmcp.me";
const API_KEY = "zmcp_sua_api_key_aqui";

// Enviar mensagem
async function sendMessage(to, text) {
  const response = await fetch(`${API_URL}/api/v1/messages`, {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ to, text })
  });

  return response.json();
}

sendMessage("+5511999999999", "Olá via Node.js!")
  .then(console.log);

Códigos de Erro

CódigoDescrição
400Requisição inválida (parâmetros incorretos)
401API key inválida ou ausente
403Acesso negado (assinatura inativa)
404Recurso não encontrado
429Rate limit excedido (aguarde e tente novamente)
503WhatsApp desconectado (reconecte no dashboard)

Rate Limits

O plano Pro permite 100K chamadas de API por mês. Precisa de mais? Entre em contato para um plano personalizado.

Webhooks (Em Breve)

Receba notificações em tempo real quando mensagens chegarem. Configure uma URL e receba eventos automaticamente no seu servidor.