API Reference

Documentacao completa da API REST. Integre seu WhatsApp com qualquer aplicacao.

Autenticacao

Todas as requisicoes devem incluir o header X-API-Key com sua API key:

curl -X GET "https://sua-instancia.z-mcp.com/api/v1/status" \
  -H "X-API-Key: zmcp_sua_api_key_aqui"

Obtendo sua API key

Acesse o dashboard da sua instancia, va em Configuracoes e copie sua API key. Cada instancia tem sua propria chave. Mantenha-a em seguranca.

Base URL

Cada instancia tem sua propria URL. Voce encontra no dashboard:

https://sua-instancia.z-mcp.com

Endpoints

GET/api/v1/status

Verifica o status da conexao 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": "Ola! Esta e 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 maxima (default: 50)
sinceData inicial (ISO 8601)

Response:

{
  "messages": [
    {
      "id": "msg_abc123",
      "chat_id": "[email protected]",
      "from": "+5511888888888",
      "text": "Ola!",
      "timestamp": 1703894400,
      "is_from_me": false
    }
  ],
  "count": 1
}
GET/api/v1/contacts

Busca contatos

Query Parameters:

qTermo de busca (nome ou telefone)
limitQuantidade maxima (default: 20)

Response:

{
  "contacts": [
    {
      "jid": "[email protected]",
      "name": "Joao Silva",
      "phone": "+5511999999999",
      "is_group": false
    }
  ]
}
GET/api/v1/chats/{chat_id}/history

Historico completo de um chat

Query Parameters:

limitQuantidade maxima (default: 100)

Response:

{
  "chat_id": "[email protected]",
  "messages": [
    {
      "id": "msg_abc123",
      "text": "Ola!",
      "timestamp": 1703894400,
      "is_from_me": false
    }
  ],
  "count": 50
}

Exemplos

cURL

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

Python

import requests

API_URL = "https://sua-instancia.z-mcp.com"
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": "Ola via Python!"
    }
)

print(response.json())

Node.js

const API_URL = "https://sua-instancia.z-mcp.com";
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", "Ola via Node.js!")
  .then(console.log);

Codigos de Erro

CodigoDescricao
400Requisicao invalida (parametros incorretos)
401API key invalida ou ausente
403Acesso negado (subscription inativa)
404Recurso nao encontrado
429Rate limit excedido (aguarde e tente novamente)
503WhatsApp desconectado (reconecte no dashboard)

Rate Limits

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

Webhooks (Em Breve)

Receba notificacoes em tempo real quando mensagens chegarem. Configure uma URL e receba eventos automaticamente no seu servidor.