📄 Documentacao da API

← Voltar ao Painel

WhatsApp API — Referencia dos Endpoints

Documentacao completa de todos os endpoints REST e eventos Socket.io para integracao com o WhatsApp via Baileys.

Base URL /api Content-Type application/json Auth Nenhuma WebSocket Socket.io v4
Conexao & Status
GET/api/statusEstado atual da conexao▶

Retorna o estado atual da conexao WhatsApp, numero e nome do usuario conectado.

curl 
curl -X GET https://seu-dominio.com/api/status
Respostas
200
Conectado 
{ "success": true, "status": "connected", "phone": "5511999999999@s.whatsapp.net", "name": "Joao" }
200
Desconectado 
{ "success": true, "status": "disconnected", "phone": null, "name": null }
Use o evento connection_status do Socket.io para atualizacoes em tempo real sem polling.
POST/api/connectInicia a conexao▶

Inicia ou reinicia a conexao. Se existir sessao salva, conecta automaticamente. Caso contrario, gera QR Code via Socket.io.

curl 
curl -X POST https://seu-dominio.com/api/connect
Respostas
200
{ "success": true, "message": "Conectando..." }
POST/api/disconnectEncerra a conexao mantendo a sessao▶

Fecha o socket sem apagar os arquivos de sessao. Na proxima conexao, nao sera necessario escanear o QR novamente.

curl 
curl -X POST https://seu-dominio.com/api/disconnect
Respostas
200
{ "success": true, "message": "Desconectado com sucesso." }
POST/api/resetApaga a sessao e gera novo QR▶

Apaga todos os arquivos de sessao e reinicia a autenticacao. Alias: /api/logout.

Acao irreversivel. O numero conectado precisara escanear o QR novamente.
curl 
curl -X POST https://seu-dominio.com/api/reset
Respostas
200
{ "success": true, "message": "Sessao resetada - novo QR Code sera gerado." }
Envio de Mensagens
POST/api/send-messageEnvia mensagem de texto▶

Envia texto. Exibe digitando... automaticamente antes de enviar. Alias: /api/send/text.

Body (JSON)
CampoTipoObrig.Descricao
phonestringSimNumero DDI+DDD+numero. Ex: 5511999999999. Aceita to.
messagestringSimTexto da mensagem. Aceita text.
senderNamestringNaoPrefixa com [Nome]. Ex: "Suporte" vira "[Suporte] Ola!". Aceita sender_name.
curl 
curl -X POST https://seu-dominio.com/api/send-message -H "Content-Type: application/json" -d '{"phone":"5511999999999","message":"Ola!","senderName":"Suporte"}'
Python 
r = requests.post("https://seu-dominio.com/api/send-message",
    json={"phone": "5511999999999", "message": "Ola!", "senderName": "Suporte"})
Respostas
200
{ "success": true, "message": "Mensagem enviada com sucesso." }
400
{ "success": false, "message": "Os campos phone e message sao obrigatorios." }
503
{ "success": false, "message": "WhatsApp nao esta conectado" }
POST/api/send-imageEnvia imagem por URL▶

Envia imagem a partir de URL publica. Para upload de arquivo use /api/send/image.

Body (JSON)
CampoTipoObrig.Descricao
phonestringSimNumero do destinatario. Aceita to.
imageUrlstringSimURL publica da imagem (jpg, png, gif, webp). Aceita image_url.
captionstringNaoLegenda da imagem.
senderNamestringNaoPrefixo [Nome] na legenda.
curl 
curl -X POST https://seu-dominio.com/api/send-image -H "Content-Type: application/json" -d '{"phone":"5511999999999","imageUrl":"https://exemplo.com/foto.jpg","caption":"Promocao!"}'
Respostas
200
{ "success": true, "message": "Imagem enviada com sucesso." }
400
{ "success": false, "message": "Os campos phone e imageUrl sao obrigatorios." }
503
{ "success": false, "message": "WhatsApp nao esta conectado" }
POST/api/send/imageEnvia imagem via upload multipart▶

Envia imagem como upload multipart/form-data. Limite: 10 MB.

Body (multipart/form-data)
CampoTipoObrig.Descricao
phonestringSimNumero do destinatario.
imagefileSim*Arquivo de imagem. *Obrigatorio se imageUrl nao for fornecido.
imageUrlstringNaoAlternativa ao arquivo.
captionstringNaoLegenda da imagem.
senderNamestringNaoPrefixo [Nome] na legenda.
curl 
curl -X POST https://seu-dominio.com/api/send/image -F "phone=5511999999999" -F "caption=Foto!" -F "image=@/caminho/foto.jpg"
Respostas
200
{ "success": true, "message": "Imagem enviada com sucesso." }
400
{ "success": false, "message": "Envie um arquivo via multipart ou forneca imageUrl." }
POST/api/send-contactEnvia cartao de contato vCard▶

Envia um contato no formato vCard. O destinatario podera salvar diretamente pelo WhatsApp.

Body (JSON)
CampoTipoObrig.Descricao
phonestringSimNumero do destinatario.
contactNamestringSimNome de exibicao do contato a ser enviado.
contactPhonestringSimNumero do contato a ser enviado (com DDI).
curl 
curl -X POST https://seu-dominio.com/api/send-contact -H "Content-Type: application/json" -d '{"phone":"5511999999999","contactName":"Maria","contactPhone":"5511888888888"}'
Respostas
200
{ "success": true, "message": "Contato enviado com sucesso." }
400
{ "success": false, "message": "Os campos phone, contactName e contactPhone sao obrigatorios." }
POST/api/typingExibe digitando... manualmente▶

Exibe o indicador de digitacao pelo tempo especificado. Nos endpoints de envio, a digitacao ja e automatica.

Body (JSON)
CampoTipoObrig.Descricao
phonestringSimNumero do destinatario. Aceita to.
durationnumberNaoDuracao em ms. Min: 500 / Max: 15000 / Padrao: 3000.
curl 
curl -X POST https://seu-dominio.com/api/typing -H "Content-Type: application/json" -d '{"phone":"5511999999999","duration":4000}'
Respostas
200
{ "success": true, "message": "Indicador digitando... enviado." }
400
{ "success": false, "message": "duration deve ser numero positivo em milissegundos." }
Inbox - Mensagens Recebidas
GET/api/messages/recentUltimas mensagens recebidas▶

Retorna o buffer circular das ultimas mensagens recebidas (max. 50), mantidas em memoria.

Query Params
ParametroTipoObrig.Descricao
limitnumberNaoQuantidade de mensagens. Padrao: 50. Maximo: 50.
curl 
curl "https://seu-dominio.com/api/messages/recent?limit=10"
Python 
r = requests.get("https://seu-dominio.com/api/messages/recent", params={"limit": 10})
Resposta 200
Sucesso 
{ "success": true, "count": 1, "messages": [{ "messageId": "3EB0...", "from": "5511999999999", "name": "Joao", "message": "Ola", "type": "text", "timestamp": 1742000000, "isGroup": false }] }
Eventos Socket.io em Tempo Real

Conecte via Socket.io para receber atualizacoes em tempo real sem polling.

Conexao Python 
import socketio, requests
sio = socketio.Client()
sio.connect("https://seu-dominio.com", transports=["websocket"])
sio.wait()
connection_statusservidor → cliente

Emitido a cada mudanca de estado do WhatsApp e ao conectar (snapshot atual).

Payload 
{ "state": "connected", "phone": "5511999999999@s.whatsapp.net", "name": "Joao", "qr": "data:image/png;base64,..." }
qr_codeservidor → cliente

Emitido a cada novo QR Code gerado (~60s de validade).

Payload 
{ "qr": "data:image/png;base64,iVBORw0KGgo..." }
message_receivedservidor → cliente

Emitido para cada mensagem recebida (exceto broadcasts e mensagens proprias).

Payload 
{ "messageId": "3EB0...", "from": "5511999999999", "name": "Joao", "message": "Ola!", "type": "text", "timestamp": 1742000000, "isGroup": false }
recent_messagesservidor → cliente

Buffer das ultimas 50 mensagens, enviado ao conectar e em resposta ao evento get_recent_messages.

Payload 
[{ "messageId": "...", "from": "551199...", "message": "...", "type": "text", "timestamp": 1742000000, "isGroup": false }]
get_recent_messagescliente → servidor

Emita este evento para solicitar o buffer. O servidor responde com recent_messages.

Exemplo 
sio.emit("get_recent_messages")