WhatsApp API
Envie mensagens e ficheiros via WhatsApp. Retorna message_id em cada envio.
Autenticação
A API suporta 2 métodos de autenticação:
Token temporário (24h). Mais seguro, suporta refresh.
✅ Recomendado para produção
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.
Método 2: API Key + Secret
Obtenha no painel: Configurações → API Keys → Gerar Nova API Key
O API Secret só é exibido uma vez. Guarde em local seguro.
Erros de Autenticação
| Erro | Causa |
|---|---|
| 401 | Token ausente, inválido ou expirado |
| 403 | Sem permissão para este recurso |
| 400 | Falta 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.
| Estado | Descrição |
|---|---|
created | Criada, ainda não ligada |
connecting | Em processo de ligação (aguarda QR ou código) |
connected | Activa — pronta para enviar e receber |
disconnected | Desligada (pode reconectar) |
logged_out | Sessão encerrada (pode reconectar) |
replaced | Substituída por outra sessão no mesmo número |
banned | Nú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.
POST /whatsapp/sessionspara criar e guardar osession_idPOST /whatsapp/sessions/:id/connect(QR) ouPOST /whatsapp/sessions/:id/connect/code(código)GET /whatsapp/sessions/:id/statusaté o estado ficarconnected
Forma tradicional. Abre o WhatsApp no telemóvel, tira foto do QR Code e fica ligado.
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.
- Use um
namedescritivo por equipa/uso (ex.:suporte-maputo) - Evite nomes duplicados para facilitar monitoria e suporte
- Guarde o
data.session_idno banco para reuso em todos os endpoints
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
POST /whatsapp/sessions/:id/connect— inicia a ligação- Obter QR — dois endpoints disponíveis:
GET /sessions/:id/qr— JSON comqr_code(texto). Renderizar com biblioteca (ex:qrcode.js)GET /sessions/:id/qr/image— imagem PNG directa (302 redirect). Usar em<img src>
- 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
POST /whatsapp/sessions/:id/connect/codecom número de telefone- Resposta retorna código de 8 dígitos:
"code": "ABCD-1234" - No telemóvel: WhatsApp → Dispositivos Vinculados → Inserir código
Outras operações de sessão
| Acção | Rota |
|---|---|
| Ver estado em tempo real | GET /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ão | GET /whatsapp/sessions/:id/details |
| Configurações | GET/PUT /whatsapp/sessions/:id/settings |
| Configurar webhook | POST /whatsapp/sessions/:id/webhooks |
| Remover sessão | DELETE /whatsapp/sessions/:id |
| Grupos da sessão | GET /whatsapp/sessions/:id/groups |
| Membros de grupo | GET /whatsapp/sessions/:id/groups/:jid/members |
| Contactos | GET /whatsapp/sessions/:id/contacts |
| Sincronizar grupos | POST /whatsapp/sessions/:id/sync/groups |
| Sincronizar contactos | POST /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ódigo | Significado |
|---|---|
| 200 | Sucesso |
| 400 | Parâmetros em falta |
| 401 | Token inválido |
| 402 | Sem plano activo |
| 403 | WAF bloqueou (falta header Referer) |
| 413 | Ficheiro > 15 MB |
| 415 | Tipo não suportado |
| 502 | Sessão desligada ou timeout |
Ficheiros Suportados
| Tipo | MIME Types |
|---|---|
| Imagem | image/jpeg, image/png, image/gif, image/webp |
| Vídeo | video/mp4, video/mpeg, video/quicktime, video/webm |
| Áudio | audio/mpeg, audio/ogg, audio/wav, audio/aac |
| Documento | application/pdf, .doc, .docx, .xls, .xlsx |
Tipo detectado por bytes mágicos. Limite: 15 MB. Rate limit: 100 req/min.
data.session_id para usar nos próximos endpoints de ligação e gestão.- Enviar
namecom identificador simples da sessão (ex.:suporte-1) - Guardar o
data.session_idno seu sistema - Iniciar ligação com
POST /whatsapp/sessions/:id/connect(QR) ou/connect/code - Consultar
GET /whatsapp/sessions/:id/statuspara acompanhar transição atéconnected
| Campo | Tipo | Descrição |
|---|---|---|
nameobrigatório |
string | Nome da sessão |
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']
POST para a sua URL com event, user_id, timestamp e data com os detalhes do evento.- Registe uma URL pública HTTPS por sessão com os eventos que pretende receber
- Quando algo acontecer, a MozeSMS envia um
POSTJSON para a sua URL - O seu endpoint deve responder
200rapidamente para confirmar receção - Use
secretpara validar o headerX-Webhook-Secretno seu servidor
| Campo | Tipo | Descriçã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. |
| Evento | Quando dispara | Campos 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 |
Todos os eventos seguem a estrutura event, user_id, timestamp e data. O conteúdo de data muda conforme o evento.
Valide X-Webhook-Secret, aceite apenas HTTPS e responda 200 antes de processamentos pesados ou filas internas.
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.
- Criar a sessão e ligar o número ao WhatsApp
- Registar o webhook em
POST /whatsapp/sessions/:session_id/webhooks - Receber
POSTda MozeSMS comevent,user_id,timestampedata - Validar
X-Webhook-Secrete responder200rapidamente
| Categoria | Eventos | Uso 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 |
Responda 200 o mais rápido possível e envie processamento pesado para fila ou worker interno.
Dê prioridade a session.logged_out e whatsapp.failed para alertas e recuperação automática.
phone (único) e phones[] (massa).| Campo | Tipo | Descriçã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. |
type + campo específico para controlo total, ou type + url quando o ficheiro já está hospedado.
| type | Campo principal | url | Uso 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 |
message_id e log_id.session_id, phone, message).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"
}
multipart/form-data. Requer header Referer (WAF).| Header | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório |
string | Bearer {token} |
Refererobrigatório |
string | URL do seu domínio (ex: https://meudominio.com) — obrigatório para multipart. |
| Campo | Tipo | Descriçã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). |
message_id, phone e log_id.session_id, phone, file).Referer.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"
}
Referer.| Campo | Tipo | Descrição |
|---|---|---|
fileobrigatório |
file | Ficheiro a armazenar. Tipo detectado automaticamente por bytes mágicos. Máx. 15 MB. |
url, mime e size.file em falta.Referer.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"
}
| Campo | Tipo | Descriçã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. |
message_id e log_id.type inválido.# 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)