MozeSMS
WhatsApp API / Documentação
REST API  ·  WhatsApp Business

WhatsApp API

Envie mensagens e ficheiros via WhatsApp. Retorna message_id em cada envio.

https://api.mozesms.com

Autenticação

A API suporta 2 métodos de autenticação:

Bearer Token (JWT)

Token temporário (24h). Mais seguro, suporta refresh.
✅ Recomendado para produção

API Key + Secret

Credenciais permanentes. Simples de implementar.
✅ Bom para scripts e automação

Método 1: Bearer Token

Token obtido via POST /auth/login. Válido 24h. Renovável via POST /auth/refresh.

Authorization: Bearer eyJhbGci...

Método 2: API Key + Secret

Obtenha no painel: Configurações → API Keys → Gerar Nova API Key

X-API-Key: mzs_live_abc123...
X-API-Secret: sk_live_xyz123...

O API Secret só é exibido uma vez. Guarde em local seguro.

Erros de Autenticação

ErroCausa
401Token ausente, inválido ou expirado
403Sem permissão para este recurso
400Falta X-API-Key ou X-API-Secret
curl -X POST "https://api.mozesms.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"seu@email.com","password":"senha"}'
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "rt_abc123...",
    "expires_in": 86400
  }
}
curl -X POST "https://api.mozesms.com/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"rt_abc123..."}'
curl -X POST "https://api.mozesms.com/whatsapp/send" \
  -H "X-API-Key: mzs_live_abc123" \
  -H "X-API-Secret: sk_live_xyz789" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"suporte","phone":"258841234567","message":"Olá!"}'
$ch = curl_init('https://api.mozesms.com/auth/login');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'seu@email.com',
    'password' => 'senha',
  ]),
]);
$res = json_decode(curl_exec($ch), true);
$token = $res['data']['token'];
$refresh = $res['data']['refresh_token'];
$ch = curl_init('https://api.mozesms.com/whatsapp/send');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: mzs_live_abc123',
    'X-API-Secret: sk_live_xyz789',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'session_id' => 'suporte',
    'phone' => '258841234567',
    'message' => 'Olá!',
  ]),
]);
$res = json_decode(curl_exec($ch), true);
import requests

res = requests.post(
    'https://api.mozesms.com/auth/login',
    json={'email': 'seu@email.com', 'password': 'senha'}
)
token = res.json()['data']['token']
refresh = res.json()['data']['refresh_token']
requests.post(
    'https://api.mozesms.com/whatsapp/send',
    headers={
        'X-API-Key': 'mzs_live_abc123',
        'X-API-Secret': 'sk_live_xyz789'
    },
    json={
        'session_id': 'suporte',
        'phone': '258841234567',
        'message': 'Olá!'
    }
)
res = requests.post(
    'https://api.mozesms.com/auth/refresh',
    json={'refresh_token': refresh}
)
token = res.json()['data']['token']

Conceitos

Sessão

Número WhatsApp ligado à plataforma. Cada sessão tem um session_id único.

EstadoDescrição
createdCriada, ainda não ligada
connectingEm processo de ligação (aguarda QR ou código)
connectedActiva — pronta para enviar e receber
disconnectedDesligada (pode reconectar)
logged_outSessão encerrada (pode reconectar)
replacedSubstituída por outra sessão no mesmo número
bannedNúmero banido pelo WhatsApp

Formato de Número

Código país + número, sem + nem espaços: 258845888195

Plano de Instância

Cada sessão precisa de plano activo. Sem plano → HTTP 402.

Formas de Conectar ao WhatsApp

Para conectar ao WhatsApp, primeiro crie a sessão e só depois escolha QR Code ou código de pareamento.

Fluxo recomendado
  1. POST /whatsapp/sessions para criar e guardar o session_id
  2. POST /whatsapp/sessions/:id/connect (QR) ou POST /whatsapp/sessions/:id/connect/code (código)
  3. GET /whatsapp/sessions/:id/status até o estado ficar connected
QR Code (Câmara)

Forma tradicional. Abre o WhatsApp no telemóvel, tira foto do QR Code e fica ligado.

Código (Sem Câmara)

Alternativa sem câmara. Recebe código de 8 dígitos para introduzir manualmente no WhatsApp.

1. Criar Sessão

Este passo prepara a instância que será ligada ao dispositivo. Sem session_id não é possível gerar QR nem código de pareamento.

Checklist rápido antes de criar
  • Use um name descritivo por equipa/uso (ex.: suporte-maputo)
  • Evite nomes duplicados para facilitar monitoria e suporte
  • Guarde o data.session_id no banco para reuso em todos os endpoints
Request mínimo recomendado
POST /whatsapp/sessions com {"name":"suporte-maputo"}

Resultado esperado: 201 com data.session_id e estado inicial created.

O campo name aceita apenas letras, números e hífens. Se não houver plano activo, a API retorna HTTP 402.

2. Conectar via QR Code

  1. POST /whatsapp/sessions/:id/connect — inicia a ligação
  2. Obter QR — dois endpoints disponíveis:
    • GET /sessions/:id/qr — JSON com qr_code (texto). Renderizar com biblioteca (ex: qrcode.js)
    • GET /sessions/:id/qr/image — imagem PNG directa (302 redirect). Usar em <img src>
  3. No telemóvel: WhatsApp → Dispositivos Vinculados → Vincular

QR expira em ~60s. Se expirar, chame POST /connect novamente.

Ambos retornam HTTP 409 se a sessão estiver em modo pairing_code.

3. Conectar via Código de Pareamento

  1. POST /whatsapp/sessions/:id/connect/code com número de telefone
  2. Resposta retorna código de 8 dígitos: "code": "ABCD-1234"
  3. No telemóvel: WhatsApp → Dispositivos Vinculados → Inserir código

Outras operações de sessão

AcçãoRota
Ver estado em tempo realGET /whatsapp/sessions/:id/status
QR Code (texto JSON)GET /whatsapp/sessions/:id/qr
QR Code (imagem PNG)GET /whatsapp/sessions/:id/qr/image
Detalhes da sessãoGET /whatsapp/sessions/:id/details
ConfiguraçõesGET/PUT /whatsapp/sessions/:id/settings
Configurar webhookPOST /whatsapp/sessions/:id/webhooks
Remover sessãoDELETE /whatsapp/sessions/:id
Grupos da sessãoGET /whatsapp/sessions/:id/groups
Membros de grupoGET /whatsapp/sessions/:id/groups/:jid/members
ContactosGET /whatsapp/sessions/:id/contacts
Sincronizar gruposPOST /whatsapp/sessions/:id/sync/groups
Sincronizar contactosPOST /whatsapp/sessions/:id/sync/contacts
curl -X POST "https://api.mozesms.com/whatsapp/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Suporte"}'
{
  "session_id": "17c6074e-3359-..."
}
curl -X POST "https://api.mozesms.com/whatsapp/sessions/17c6074e.../connect" \
  -H "Authorization: Bearer $TOKEN"
<img src="https://api.mozesms.com/whatsapp/sessions/17c6074e.../qr/image"
     alt="QR Code" width="256" />
curl -X GET "https://api.mozesms.com/whatsapp/sessions/17c6074e.../qr" \
  -H "Authorization: Bearer $TOKEN"
{ "success": true, "data": { "qr_code": "2@90VW97Q0Rm..." } }
<!-- cdn.jsdelivr.net/npm/qrcode/build/qrcode.min.js -->
<canvas id="qr"></canvas>
<script>
  QRCode.toCanvas(document.getElementById('qr'), "2@90VW97Q0Rm...");
</script>
curl -X POST "https://api.mozesms.com/whatsapp/sessions/17c6074e.../connect/code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "258841234567"}'
{
  "code": "ABCD-1234"
}
$ch = curl_init('https://api.mozesms.com/whatsapp/sessions');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  ],
  CURLOPT_POSTFIELDS => json_encode(['name' => 'Suporte'])
]);
$res = json_decode(curl_exec($ch), true);
$sessionId = $res['session_id'];
$ch = curl_init("https://api.mozesms.com/whatsapp/sessions/{$sessionId}/connect");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token]
]);
curl_exec($ch);
// /qr/image devolve PNG via redirect 302
echo "<img src='https://api.mozesms.com/whatsapp/sessions/{$sessionId}/qr/image'
     alt='QR Code' width='256' />";
$ch = curl_init("https://api.mozesms.com/whatsapp/sessions/{$sessionId}/qr");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token]
]);
$text = json_decode(curl_exec($ch), true)['data']['qr_code'];
// composer require chillerlan/php-qrcode
$png = (new QRCode())->render($text);
echo "<img src='data:image/png;base64," . base64_encode($png) . "' />";
$ch = curl_init("https://api.mozesms.com/whatsapp/sessions/{$sessionId}/connect/code");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  ],
  CURLOPT_POSTFIELDS => json_encode(['phone' => '258841234567'])
]);
$res = json_decode(curl_exec($ch), true);
echo "Código: " . $res['code']; // ABCD-1234
import requests

res = requests.post(
    'https://api.mozesms.com/whatsapp/sessions',
    headers={'Authorization': f'Bearer {token}'},
    json={'name': 'Suporte'}
)
session_id = res.json()['session_id']
requests.post(
    f'https://api.mozesms.com/whatsapp/sessions/{session_id}/connect',
    headers={'Authorization': f'Bearer {token}'}
)
# /qr/image devolve PNG via redirect 302
qr_img_url = f'https://api.mozesms.com/whatsapp/sessions/{session_id}/qr/image'
print(f'<img src="{qr_img_url}" alt="QR Code" width="256" />')
res = requests.get(
    f'https://api.mozesms.com/whatsapp/sessions/{session_id}/qr',
    headers={'Authorization': f'Bearer {token}'}
)
qr_text = res.json()['data']['qr_code']
# pip install qrcode pillow
import qrcode
qrcode.make(qr_text).save('qr.png')
res = requests.post(
    f'https://api.mozesms.com/whatsapp/sessions/{session_id}/connect/code',
    headers={'Authorization': f'Bearer {token}'},
    json={'phone': '258841234567'}
)
code = res.json()['code']
print(f'Código: {code}')  # ABCD-1234

Erros & Limites

CódigoSignificado
200Sucesso
400Parâmetros em falta
401Token inválido
402Sem plano activo
403WAF bloqueou (falta header Referer)
413Ficheiro > 15 MB
415Tipo não suportado
502Sessão desligada ou timeout

Ficheiros Suportados

TipoMIME Types
Imagemimage/jpeg, image/png, image/gif, image/webp
Vídeovideo/mp4, video/mpeg, video/quicktime, video/webm
Áudioaudio/mpeg, audio/ogg, audio/wav, audio/aac
Documentoapplication/pdf, .doc, .docx, .xls, .xlsx

Tipo detectado por bytes mágicos. Limite: 15 MB. Rate limit: 100 req/min.

Sessões
Criar, ligar, monitorar e remover sessões WhatsApp
Sessões/Criar sessão
POST/whatsapp/sessions
Criar Sessão
Cria nova sessão WhatsApp. Retorna data.session_id para usar nos próximos endpoints de ligação e gestão.
Como fazer (passo a passo)
  1. Enviar name com identificador simples da sessão (ex.: suporte-1)
  2. Guardar o data.session_id no seu sistema
  3. Iniciar ligação com POST /whatsapp/sessions/:id/connect (QR) ou /connect/code
  4. Consultar GET /whatsapp/sessions/:id/status para acompanhar transição até connected
Body (JSON)
CampoTipoDescrição
nameobrigatório string Nome da sessão
Respostas
201Sessão criada
401Não autenticado

Remover sessão

Endpoint: DELETE /whatsapp/sessions/:session_id. Exemplo de código no painel direito.

curl -X POST "https://api.mozesms.com/whatsapp/sessions" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Suporte"}'
{
  "success": true,
  "data": {
    "session_id": "17c6074e-3359-..."
  }
}
curl -X DELETE "https://api.mozesms.com/whatsapp/sessions/17c6074e-3359-..." \
    -H "Authorization: Bearer $TOKEN"
$ch = curl_init('https://api.mozesms.com/whatsapp/sessions');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  ],
  CURLOPT_POSTFIELDS => json_encode(['name' => 'Suporte'])
]);
$res = json_decode(curl_exec($ch), true);
$sessionId = $res['data']['session_id'];
import requests

res = requests.post(
    'https://api.mozesms.com/whatsapp/sessions',
    headers={'Authorization': f'Bearer {token}'},
    json={'name': 'Suporte'}
)
session_id = res.json()['data']['session_id']
Sessões/Configurar webhook
POST/whatsapp/sessions/:session_id/webhooks
Configurar Webhook da Sessão
Regista URL de callback para receber eventos em tempo real. A MozeSMS faz POST para a sua URL com event, user_id, timestamp e data com os detalhes do evento.
Como funciona
  • Registe uma URL pública HTTPS por sessão com os eventos que pretende receber
  • Quando algo acontecer, a MozeSMS envia um POST JSON para a sua URL
  • O seu endpoint deve responder 200 rapidamente para confirmar receção
  • Use secret para validar o header X-Webhook-Secret no seu servidor
Body parameters (JSON)
CampoTipoDescrição
urlobrigatório string Endpoint HTTPS público do seu servidor (ex: https://seusite.com/webhook/whatsapp).
eventsobrigatório array Lista de eventos para subscrever (ex: whatsapp.received, whatsapp.delivered, session.logged_out).
secretopcional string Chave para validar assinatura dos callbacks recebidos.
Eventos disponíveis
EventoQuando disparaCampos principais
whatsapp.received Cliente envia mensagem para a sessão. message_id, from, type, message/caption, session_id
whatsapp.sent Mensagem aceite/enviada pela plataforma. message_id, phone, status, session_id
whatsapp.delivered Mensagem entregue no dispositivo destino. message_id, phone, status, event_time
whatsapp.read Destinatário abriu e leu a mensagem. message_id, phone, status, event_time
whatsapp.failed Falha no envio ou entrega. message_id, phone, error, error_code, session_id
session.connected Sessão voltou a ficar ligada. session_id, phone, status, connected
session.logged_out WhatsApp removeu a sessão do aparelho. session_id, phone, status, reason
session.disconnected Queda temporária de ligação. session_id, phone, status, reason
Payload base

Todos os eventos seguem a estrutura event, user_id, timestamp e data. O conteúdo de data muda conforme o evento.

Segurança

Valide X-Webhook-Secret, aceite apenas HTTPS e responda 200 antes de processamentos pesados ou filas internas.

Respostas
200Webhook registado com sucesso.
400Payload inválido ou URL mal formatada.
401Token inválido ou expirado.
curl -X POST "https://api.mozesms.com/whatsapp/sessions/17c6074e-3359-.../webhooks" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "url": "https://seusite.com/webhook/whatsapp",
        "events": [
            "whatsapp.received",
            "whatsapp.delivered",
            "whatsapp.read",
            "session.logged_out"
        ],
        "secret": "chave_secreta_123"
    }'
{
    "success": true,
    "data": {
        "webhook_id": "wh_abc123",
        "url": "https://seusite.com/webhook/whatsapp",
        "events_count": 4
    }
}
{
    "event": "whatsapp.received",
    "user_id": 42,
    "timestamp": "2026-04-20T14:30:15+02:00",
    "data": {
        "message_id": "XYZ123456789",
        "from": "258841234567",
        "session_id": "atendimento-clientes",
        "type": "text",
        "message": "Olá, preciso de ajuda",
        "event_time": "2026-04-20 14:30:15",
        "name": "João Silva",
        "is_group": false
    }
}
$payload = [
    'url' => 'https://seusite.com/webhook/whatsapp',
    'events' => [
        'whatsapp.received',
        'whatsapp.delivered',
        'whatsapp.read',
        'session.logged_out',
    ],
    'secret' => 'chave_secreta_123',
];

$ch = curl_init("https://api.mozesms.com/whatsapp/sessions/{$sessionId}/webhooks");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);
$res = json_decode(curl_exec($ch), true);
$secret = 'chave_secreta_123';
$receivedSecret = $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '';

if ($receivedSecret !== $secret) {
    http_response_code(401);
    exit;
}

$webhook = json_decode(file_get_contents('php://input'), true);
$event = $webhook['event'] ?? '';
$data = $webhook['data'] ?? [];

if ($event === 'whatsapp.received') {
    // Guardar mensagem / disparar chatbot / abrir ticket
}

http_response_code(200);
echo json_encode(['success' => true]);
import requests

payload = {
        'url': 'https://seusite.com/webhook/whatsapp',
        'events': [
                'whatsapp.received',
                'whatsapp.delivered',
                'whatsapp.read',
                'session.logged_out',
        ],
        'secret': 'chave_secreta_123',
}

res = requests.post(
        f'https://api.mozesms.com/whatsapp/sessions/{session_id}/webhooks',
        headers={'Authorization': f'Bearer {token}'},
        json=payload,
        timeout=30
)
data = res.json()
from flask import Flask, request, jsonify

    app = Flask(__name__)
    WEBHOOK_SECRET = 'chave_secreta_123'

    @app.post('/webhook/whatsapp')
    def receive_webhook():
        if request.headers.get('X-Webhook-Secret') != WEBHOOK_SECRET:
            return jsonify({'error': 'unauthorized'}), 401

        webhook = request.get_json()
        event = webhook.get('event')
        data = webhook.get('data', {})

        if event == 'session.logged_out':
            print(f"Sessão removida: {data.get('session_id')}")

        return jsonify({'success': True}), 200

Guia de Webhook

Use webhooks para receber eventos do WhatsApp em tempo real no seu sistema sem fazer polling. A configuração é por sessão: registe a URL, escolha os eventos e trate os callbacks no seu endpoint.

Fluxo recomendado
  • Criar a sessão e ligar o número ao WhatsApp
  • Registar o webhook em POST /whatsapp/sessions/:session_id/webhooks
  • Receber POST da MozeSMS com event, user_id, timestamp e data
  • Validar X-Webhook-Secret e responder 200 rapidamente
Eventos principais
CategoriaEventosUso típico
Mensagens whatsapp.received, whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed Chatbot, CRM, tracking de entrega e leitura
Sessão session.connected, session.disconnected, session.logged_out Monitoria da conexão e alertas operacionais
Grupos whatsapp.group_updated, whatsapp.participant_change Sincronização de grupos e auditoria de participantes
Boas práticas

Responda 200 o mais rápido possível e envie processamento pesado para fila ou worker interno.

Eventos críticos

Dê prioridade a session.logged_out e whatsapp.failed para alertas e recuperação automática.

Mensagens WhatsApp
Enviar texto, ficheiros e media via WhatsApp Business API
Mensagens/Enviar texto
POST/whatsapp/send
Enviar mensagem de texto
Envia texto para um ou vários destinatários. Suporta phone (único) e phones[] (massa).
Body parameters (JSON)
CampoTipoDescrição
session_idobrigatório string UUID da sessão WhatsApp activa (ex: 17c6074e-3359-4a73-a513-a35953a007f2).
phoneopcional string Número único com código de país, sem + (ex: 258845888195).
phonesopcional array Lista de números para envio em massa. Use este campo em vez de phone.
typeopcional string Padrão text. Também aceita image, video, audio, document, pdf.
messageobrigatório string Conteúdo da mensagem de texto.
Tipos de média no mesmo endpoint
Use type + campo específico para controlo total, ou type + url quando o ficheiro já está hospedado.
typeCampo principalurlUso recomendado
text message Mensagens simples e rápidas
image image suporta Promoções, catálogos, comprovativos visuais
video video suporta Demos curtas, onboarding e tutoriais
audio audio suporta Atualizações por voz (use ptt=true para voz)
document document suporta Contratos, propostas, anexos gerais
pdf document suporta Faturas, relatórios e documentos finais
Respostas
200Mensagem enviada. Retorna message_id e log_id.
400Parâmetros em falta (session_id, phone, message).
401Token inválido ou expirado.
402Sem plano activo para a instância.
502Sessão desligada ou timeout do WhatsApp.
curl -X POST "https://api.mozesms.com/whatsapp/send"   -H "Authorization: Bearer eyJhbGci..."   -H "Content-Type: application/json"   -d '{
    "session_id": "17c6074e-3359-4a73-a513-a35953a007f2",
    "phone": "258845888195",
    "type": "text",
    "message": "Olá! Esta é uma mensagem de teste."
  }'
$ch = curl_init('https://api.mozesms.com/whatsapp/send');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer eyJhbGci...',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS     => json_encode([
    'session_id' => '17c6074e-3359-4a73-a513-a35953a007f2',
    'phone'      => '258845888195',
    'type'       => 'text',
    'message'    => 'Olá! Esta é uma mensagem de teste.',
  ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
import requests

res = requests.post(
    'https://api.mozesms.com/whatsapp/send',
    headers={'Authorization': 'Bearer eyJhbGci...'},
    json={
        'session_id': '17c6074e-3359-4a73-a513-a35953a007f2',
        'phone':      '258845888195',
        'type':       'text',
        'message':    'Olá! Esta é uma mensagem de teste.',
    },
    timeout=30,
)
print(res.json()['message_id'])
{
  "success": true,
  "message_id": "3EB0C767D9A2F3A4B5C6",
  "log_id": 1234
}
curl -X POST "https://api.mozesms.com/whatsapp/send" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "session_id": "suporte-ao-cliente",
        "type": "text",
        "message": "Promoção especial de Abril! Válida até 30/04.",
        "phones": [
            "258841111111",
            "258842222222",
            "258843333333",
            "258844444444",
            "258845555555",
            "258846666666",
            "258847777777"
        ]
    }'
{
    "session_id": "suporte-ao-cliente",
    "type": "text",
    "message": "Promoção especial de Abril! Válida até 30/04.",
    "phones": [
        "258841111111",
        "258842222222",
        "258843333333",
        "258844444444",
        "258845555555",
        "258846666666",
        "258847777777"
    ]
}
{
    "success": true,
    "sent_count": 5,
    "queued_count": 2,
    "total": 7,
    "results": [
        { "success": true,  "phone": "258841111111", "message_id": "AAA001", "log_id": 101 },
        { "success": true,  "phone": "258842222222", "message_id": "AAA002", "log_id": 102 },
        { "success": false, "phone": "258843333333", "error": "Provider error", "log_id": 103 },
        { "success": true,  "phone": "258844444444", "message_id": "AAA004", "log_id": 104 },
        { "success": true,  "phone": "258845555555", "message_id": "AAA005", "log_id": 105 }
    ]
}
{
  "success": false,
  "error": "session not connected"
}
WhatsApp/Enviar ficheiro (upload)
POST/whatsapp/send/upload
Enviar ficheiro via upload
Upload direto por multipart/form-data. Requer header Referer (WAF).
Headers
HeaderTipoDescrição
Authorizationobrigatório string Bearer {token}
Refererobrigatório string URL do seu domínio (ex: https://meudominio.com) — obrigatório para multipart.
Body parameters (multipart/form-data)
CampoTipoDescrição
session_idobrigatório string UUID da sessão WhatsApp activa.
phoneobrigatório string Número com código de país, sem +.
fileobrigatório file Ficheiro a enviar (imagem, vídeo, áudio, documento, PDF). Máx. 15 MB.
captionopcional string Legenda do ficheiro.
filenameopcional string Nome visível do ficheiro (para documentos/PDFs).
pttopcional boolean true para enviar áudio como mensagem de voz (PTT).
Respostas
200Ficheiro enviado. Retorna message_id, phone e log_id.
400Parâmetros em falta (session_id, phone, file).
401Token inválido ou expirado.
403WAF bloqueou o request. Adicione o header Referer.
413Ficheiro maior que 15 MB.
502Sessão desligada ou timeout do WhatsApp.
curl -X POST "https://api.mozesms.com/whatsapp/send/upload"   -H "Authorization: Bearer eyJhbGci..."   -H "Referer: https://meudominio.com"   -F "session_id=17c6074e-3359-4a73-a513-a35953a007f2"   -F "phone=258845888195"   -F "file=@/caminho/para/imagem.jpg"   -F "caption=Veja esta imagem!"
$ch = curl_init('https://api.mozesms.com/whatsapp/send/upload');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer eyJhbGci...',
    'Referer: https://meudominio.com',
  ],
  CURLOPT_POSTFIELDS     => [
    'session_id' => '17c6074e-3359-4a73-a513-a35953a007f2',
    'phone'      => '258845888195',
    'file'       => new CURLFile('/caminho/para/imagem.jpg', 'image/jpeg', 'imagem.jpg'),
    'caption'    => 'Veja esta imagem!',
  ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
import requests

with open('/caminho/para/imagem.jpg', 'rb') as f:
    res = requests.post(
        'https://api.mozesms.com/whatsapp/send/upload',
        headers={
            'Authorization': 'Bearer eyJhbGci...',
            'Referer': 'https://meudominio.com',
        },
        files={'file': ('imagem.jpg', f, 'image/jpeg')},
        data={
            'session_id': '17c6074e-3359-4a73-a513-a35953a007f2',
            'phone': '258845888195',
            'caption': 'Veja esta imagem!',
        },
        timeout=60,
    )
print(res.json()['message_id'])
{
  "success": true,
  "message_id": "3EB0C767D9A2F3A4B5C6",
  "phone": "258845888195",
  "log_id": 1234
}
{
  "success": false,
  "error": "session not connected"
}
WhatsApp/Upload de ficheiro
POST/whatsapp/upload
Upload de ficheiro (armazenar)
Armazena ficheiro e retorna URL. Use no /whatsapp/send. Requer header Referer.
Body parameters (multipart/form-data)
CampoTipoDescrição
fileobrigatório file Ficheiro a armazenar. Tipo detectado automaticamente por bytes mágicos. Máx. 15 MB.
Respostas
200Ficheiro armazenado. Retorna url, mime e size.
400Campo file em falta.
401Token inválido ou expirado.
403WAF bloqueou o request. Adicione o header Referer.
413Ficheiro maior que 15 MB.
415Tipo de ficheiro não suportado.
curl -X POST "https://api.mozesms.com/whatsapp/upload"   -H "Authorization: Bearer eyJhbGci..."   -H "Referer: https://meudominio.com"   -F "file=@/caminho/para/imagem.jpg"
$ch = curl_init('https://api.mozesms.com/whatsapp/upload');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer eyJhbGci...',
    'Referer: https://meudominio.com',
  ],
  CURLOPT_POSTFIELDS     => [
    'file' => new CURLFile('/caminho/para/imagem.jpg', 'image/jpeg', 'imagem.jpg'),
  ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
$url = $res['url']; // usar em /whatsapp/send
import requests

with open('/caminho/para/imagem.jpg', 'rb') as f:
    res = requests.post(
        'https://api.mozesms.com/whatsapp/upload',
        headers={
            'Authorization': 'Bearer eyJhbGci...',
            'Referer': 'https://meudominio.com',
        },
        files={'file': ('imagem.jpg', f, 'image/jpeg')},
        timeout=60,
    )
data = res.json()
print(data['url']) # usar em /whatsapp/send
{
  "success": true,
  "url": "https://api.mozesms.com/uploads/whatsapp/2026/04/abc123.jpg",
  "mime": "image/jpeg",
  "size": 204800
}
{
  "success": false,
  "error": "unsupported file type"
}
WhatsApp/Enviar media (URL)
POST/whatsapp/send
Enviar media por URL ou base64
Envia por URL pública, URL MozeSMS ou base64 inline.
Body parameters (JSON)
CampoTipoDescrição
session_idobrigatório string UUID da sessão WhatsApp activa.
phoneobrigatório string Número com código de país, sem +.
typeobrigatório string image · video · audio · document · pdf
urlobrigatório string URL pública, URL MozeSMS ou data:image/jpeg;base64,.... URLs privadas (localhost, redes internas) são rejeitadas.
captionopcional string Legenda para imagem, vídeo ou documento.
filenameopcional string Nome visível para document e pdf.
pttopcional boolean true para enviar áudio como mensagem de voz.
Respostas
200Media enviada. Retorna message_id e log_id.
400Parâmetros em falta ou type inválido.
401Token inválido ou expirado.
502Sessão desligada, URL inacessível ou timeout.
# Enviar imagem com URL
curl -X POST "https://api.mozesms.com/whatsapp/send" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "17c6074e-3359-4a73-a513-a35953a007f2",
    "phone": "258845888195",
    "type": "image",
    "url": "https://api.mozesms.com/uploads/whatsapp/2026/04/foto.jpg",
    "caption": "Confirmação de entrega"
  }'
$ch = curl_init('https://api.mozesms.com/whatsapp/send');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer eyJhbGci...',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS     => json_encode([
    'session_id' => '17c6074e-3359-4a73-a513-a35953a007f2',
    'phone'      => '258845888195',
    'type'       => 'pdf',
    'url'        => 'https://api.mozesms.com/uploads/whatsapp/2026/04/fatura.pdf',
    'filename'   => 'Fatura_Abril_2026.pdf',
    'caption'    => 'Fatura de Abril 2026',
  ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
const res = await fetch('https://api.mozesms.com/whatsapp/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer eyJhbGci...',
    'Content-Type' : 'application/json',
  },
  body: JSON.stringify({
    session_id: '17c6074e-3359-4a73-a513-a35953a007f2',
    phone:      '258845888195',
    type:       'image',
    url:        'https://api.mozesms.com/uploads/whatsapp/2026/04/foto.jpg',
    caption:    'Confirmação de entrega',
  }),
});
const data = await res.json();
import requests

res = requests.post(
    'https://api.mozesms.com/whatsapp/send',
    headers={'Authorization': 'Bearer eyJhbGci...'},
    json={
        'session_id': '17c6074e-3359-4a73-a513-a35953a007f2',
        'phone':      '258845888195',
        'type':       'image',
        'url':        'https://api.mozesms.com/uploads/whatsapp/2026/04/foto.jpg',
        'caption':    'Confirmação de entrega',
    },
    timeout=30,
)
print(res.json()['message_id'])
{
  "success": true,
  "message_id": "3EB0C4A1B2C3D4E5F6",
  "log_id": 1234
}
{
  "success": false,
  "error": "failed to send image: session not connected"
}

Changelog

v1.0 (Abril 2026) — Lançamento inicial. Mensagens de texto e media, templates, consulta de entregas, rate limiting.

Suporte

Email: info@mozesms.com  ·  WhatsApp: +258 84 588 8195  ·  Horário: Seg-Sex, 8h-17h (GMT+2)