📚 Documentação da API

🔐 Autenticação

Todas as requisições à API requerem autenticação através do header X-API-Key.

Você pode usar a API key master fornecida pelo administrador ou criar suas próprias API keys através do sistema de gerenciamento.

🔑 Gerenciamento de API Keys

{
  "total": 2,
  "keys": [
    {
      "id": "abc123...",
      "name": "Minha API Key",
      "active": true,
      "createdAt": "2024-11-27T19:00:00.000Z",
      "lastUsed": null,
      "key": "aw_1234567..."
    }
  ]
}

{
  "name": "Nome da API Key"
}

{
  "success": true,
  "id": "abc123...",
  "name": "Nome da API Key",
  "key": "aw_abcdef1234567890...",
  "message": "API key criada com sucesso"
}

{
  "active": false,
  "name": "Novo Nome"
}

📱 Gerenciamento de Sessões

{
  "sessionId": "minha-sessao-001",
  "webhookUrl": "https://meusite.com/webhook" // opcional
}

{
  "success": true,
  "sessionId": "minha-sessao-001",
  "status": "pending",
  "message": "Sessão criada com sucesso. Busque o QR Code em GET /api/sessions/:id/qr"
}

{
  "success": true,
  "sessionId": "minha-sessao-001",
  "status": "connected",
  "message": "Sessão já existe e foi reutilizada. Busque o QR Code em GET /api/sessions/:id/qr",
  "existing": true
}

// 1. Criar sessão pela primeira vez
POST /api/sessions
{ "sessionId": "cliente-001" }
// Resposta: "Sessão criada com sucesso"

// 2. Criar novamente com o mesmo sessionId
POST /api/sessions
{ "sessionId": "cliente-001" }
// Resposta: "Sessão já existe e foi reutilizada" + "existing": true

// 3. Buscar QR code (usa a mesma sessão)
GET /api/sessions/cliente-001/qr
// Retorna QR da mesma sessão criada anteriormente

// ✅ Resultado: Sempre a mesma sessão, sem duplicações!

{
  "total": 3,
  "sessions": [
    {
      "sessionId": "minha-sessao-001",
      "status": "connected",
      "hasWebhook": true,
      "lastUpdate": "2024-11-28T10:30:00.000Z"
    }
  ]
}

{
  "sessionId": "minha-sessao-001",
  "status": "connected", // "pending", "connected", "disconnected", "not_found"
  "lastUpdate": "2024-11-28T10:30:00.000Z",
  "hasWebhook": true
}

{
  "sessionId": "minha-sessao-001",
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "status": "pending",
  "hasQr": true
}

{
  "success": true,
  "lid": "260614521942021@lid",
  "number": "5531991441439@c.us",
  "resolved": true
}

{
  "success": false,
  "lid": "260614521942021@lid",
  "number": null,
  "resolved": false,
  "message": "Não foi possível resolver o LID para um número de telefone."
}

{
  "success": true,
  "sessionId": "minha-sessao-001",
  "message": "Sessão desconectada com sucesso"
}

{
  "success": true,
  "sessionId": "minha-sessao-001",
  "message": "Sessão excluída com sucesso (incluindo arquivos do servidor)"
}

📞 Formatos de Números de Telefone

🇧🇷 Números Brasileiros

Para números brasileiros, use o formato: 55 + DDD + Número (sem o 0 inicial do DDD).

🌍 Números Internacionais

Para números de outros países, use o formato: Código do País + Número (sem espaços ou caracteres especiais).

Exemplos de Uso:

// ✅ Correto - Número brasileiro
{
  "sessionId": "minha-sessao-001",
  "to": "5571991460801",
  "message": "Olá!"
}

// ✅ Correto - Número com @c.us (também aceito)
{
  "sessionId": "minha-sessao-001",
  "to": "5571991460801@c.us",
  "message": "Olá!"
}

// ❌ Incorreto - Com caracteres especiais
{
  "to": "(71) 99146-0801"  // ERRO: não aceita parênteses e hífens
}

// ❌ Incorreto - Sem código do país
{
  "to": "71991460801"  // ERRO: falta o código 55
}

// ✅ Correto - A API normaliza automaticamente
{
  "to": "071991460801"  // ✅ Será normalizado para 5571991460801
}

💬 Envio de Mensagens

{
  "sessionId": "minha-sessao-001",
  "to": "5571991460801", // Número com DDD e código do país (55 para Brasil)
  "message": "Olá! Esta é uma mensagem de teste."
}

{
  "success": true,
  "messageId": "true_5571991460801@c.us_3EB0...",
  "to": "5571991460801@c.us",
  "timestamp": "2024-11-27T19:00:00.000Z"
}

{
  "to": "5571991460801"
}

{
  "success": true,
  "sessionId": "minha-sessao-001",
  "total": 10,
  "count": 2,
  "messages": [
    {
      "id": "true_5571991460801@c.us_3EB0...",
      "from": "5531991441439@c.us",
      "fromOriginal": "260614521942021@lid",
      "to": "5531991441439@c.us",
      "body": "Olá! Esta é uma mensagem recebida",
      "type": "chat",
      "timestamp": 1701123456789,
      "isGroup": false,
  
            

                

                    🔄 Normalização Automática de LIDs:
                
                

                    O sistema normaliza automaticamente LIDs (Linked IDs) para números reais. 
                    Quando você recebe uma mensagem de um LID (ex: 260614521942021@lid), 
                    o campo from será automaticamente convertido para o número real 
                    (ex: 5531991441439@c.us), mantendo as conversas unificadas.
                
                

                    
from: Número normalizado (use este para manter conversas unificadas)
                    
fromOriginal: ID original do WhatsApp (LID ou número) - mantido para referência
                    
O mapeamento é feito automaticamente usando histórico de envios e API do WhatsApp
                
            
    "mediaUrl": null,
      "mediaMimetype": null,
      "mediaFilename": null
    }
  ]
}

{
  "sessionId": "minha-sessao-001",
  "to": "5571991460801",
  "mediaUrl": "https://exemplo.com/imagem.jpg",
  "caption": "Legenda opcional",
  "mimetype": "image/jpeg",  // opcional
  "filename": "imagem.jpg"   // opcional
}

{
  "sessionId": "minha-sessao-001",
  "to": "5571991460801",
  "mediaBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "caption": "Legenda opcional",
  "mimetype": "image/jpeg",
  "filename": "imagem.jpg"
}

{
  "success": true,
  "messageId": "true_5571991460801@c.us_ABC123",
  "to": "5571991460801@c.us",
  "type": "media",
  "timestamp": "2024-11-27T19:00:00.000Z"
}

const response = await fetch('https://app.autowhats.com.br/api/messages/media', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sua_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sessionId: 'minha-sessao-001',
    to: '5571991460801',
    mediaUrl: 'https://exemplo.com/foto.jpg',
    caption: 'Olha essa foto!',
    mimetype: 'image/jpeg'
  })
});
const data = await response.json();

curl -X POST https://app.autowhats.com.br/api/messages/media \
  -H "X-API-Key: sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "minha-sessao-001",
    "to": "5571991460801",
    "mediaUrl": "https://exemplo.com/video.mp4",
    "caption": "Assista este vídeo!",
    "mimetype": "video/mp4"
  }'

import requests
import base64

# Ler arquivo e converter para base64
with open('audio.mp3', 'rb') as f:
    audio_base64 = base64.b64encode(f.read()).decode('utf-8')
    data_uri = f"data:audio/mpeg;base64,{audio_base64}"

response = requests.post(
    'https://app.autowhats.com.br/api/messages/media',
    headers={'X-API-Key': 'sua_api_key'},
    json={
        'sessionId': 'minha-sessao-001',
        'to': '5571991460801',
        'mediaBase64': data_uri,
        'caption': 'Escute isso!',
        'mimetype': 'audio/mpeg',
        'filename': 'audio.mp3'
    }
)
print(response.json())

 'minha-sessao-001',
    'to' => '5571991460801',
    'mediaUrl' => 'https://exemplo.com/documento.pdf',
    'caption' => 'Veja este documento',
    'mimetype' => 'application/pdf',
    'filename' => 'documento.pdf'
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

A API suporta completamente o envio e recebimento de imagens, vídeos, áudios e documentos.

📤 Enviar Mídia

Use o endpoint POST /api/messages/media para enviar mídia. Você pode enviar via URL (recomendado) ou Base64.

{
  "sessionId": "minha-sessao-001",
  "to": "5571991460801",
  "mediaUrl": "https://exemplo.com/imagem.jpg",
  "caption": "Legenda opcional",
  "mimetype": "image/jpeg",  // opcional, será detectado automaticamente
  "filename": "imagem.jpg"   // opcional
}

{
  "sessionId": "minha-sessao-001",
  "to": "5571991460801",
  "mediaBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "caption": "Legenda opcional",
  "mimetype": "image/jpeg",
  "filename": "imagem.jpg"
}

{
  "success": true,
  "messageId": "true_5571991460801@c.us_ABC123",
  "to": "5571991460801@c.us",
  "type": "media",
  "timestamp": "2024-11-27T19:00:00.000Z"
}

📥 Receber Mídia

Mídias recebidas são enviadas automaticamente via webhook (se configurado) ou podem ser consultadas via GET /api/sessions/:id/messages.

Exemplo: Mensagem com Mídia Recebida

{
  "sessionId": "minha-sessao-001",
  "from": "5571991460801@c.us",
  "to": "5571991460801@c.us",
  "body": "Legenda da imagem (se houver)",
  "type": "image",
  "timestamp": 1234567890,
  "mediaUrl": "/api/media/session-001_ABC123.jpg",
  "mediaMimetype": "image/jpeg",
  "mediaFilename": "foto.jpg",
  "isGroup": false
}

GET https://app.autowhats.com.br/api/media/session-001_ABC123.jpg

📁 Endpoint de Mídias

Mídias recebidas são armazenadas em disco e podem ser acessadas através deste endpoint público.

// JavaScript
const mediaUrl = '/api/media/session-001_ABC123.jpg';
const fullUrl = `https://app.autowhats.com.br${mediaUrl}`;
const response = await fetch(fullUrl);
const blob = await response.blob();
const imageUrl = URL.createObjectURL(blob);
document.getElementById('image').src = imageUrl;

// cURL
curl https://app.autowhats.com.br/api/media/session-001_ABC123.jpg -o imagem.jpg

// HTML
<img src="https://app.autowhats.com.br/api/media/session-001_ABC123.jpg" alt="Mídia">

📥 Recebimento de Mensagens

Existem duas formas de receber mensagens:

// Fazer polling a cada 5 segundos
setInterval(async () => {
  const response = await fetch(
    `https://app.autowhats.com.br/api/sessions/minha-sessao/messages?since=${lastTimestamp}`,
    { headers: { 'X-API-Key': 'sua_api_key' } }
  );
  const data = await response.json();
  
  if (data.messages && data.messages.length > 0) {
    data.messages.forEach(msg => {
      console.log('Nova mensagem:', msg.body);
      lastTimestamp = msg.timestamp; // Atualizar timestamp
    });
  }
}, 5000);

🔔 Webhooks

Você pode configurar um webhook ao criar uma sessão. Quando uma mensagem for recebida, a API enviará automaticamente um POST para a URL configurada.

Payload do Webhook (Mensagem de Texto):

{
  "sessionId": "minha-sessao-001",
  "from": "5571991460801@c.us",
  "to": "5571991460801@c.us",
  "body": "Mensagem recebida",
  "type": "chat",
  "timestamp": 1234567890,
  "mediaUrl": null,
  "mediaMimetype": null,
  "mediaFilename": null,
  "isGroup": false
}

Payload do Webhook (Mensagem com Mídia):

{
  "sessionId": "minha-sessao-001",
  "from": "5571991460801@c.us",
  "to": "5571991460801@c.us",
  "body": "Legenda da imagem (se houver)",
  "type": "image",  // ou "video", "audio", "document"
  "timestamp": 1234567890,
  "mediaUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "mediaMimetype": "image/jpeg",
  "mediaFilename": "foto.jpg",
  "isGroup": false
}

Exemplo: Processar Mídia Recebida (PHP):

 true]);
?>

Exemplo: Processar Mídia Recebida (Node.js):

const express = require('express');
const fs = require('fs');
const fetch = require('node-fetch');
const app = express();

app.use(express.json({ limit: '50mb' }));

app.post('/webhook', async (req, res) => {
  const { mediaUrl, mediaMimetype, mediaFilename, from, body } = req.body;
  
  if (mediaUrl) {
    // NOVO: mediaUrl agora é uma URL, não Base64
    // Baixar arquivo da API
    const fullUrl = 'https://app.autowhats.com.br' + mediaUrl;
    const response = await fetch(fullUrl);
    const buffer = await response.buffer();
    
    // Determinar extensão
    const ext = mediaMimetype.split('/')[1];
    const filename = mediaFilename || `midia_${Date.now()}.${ext}`;
    
    // Salvar arquivo
    fs.writeFileSync(`uploads/${filename}`, buffer);
    
    console.log(`Mídia recebida de ${from}: ${filename}`);
  }
  
  res.status(200).send('OK');
});

app.listen(3001);

Exemplo: Processar Mídia Recebida (Python):

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    
    if data.get('mediaUrl'):
        # NOVO: mediaUrl agora é uma URL, não Base64
        # Baixar arquivo da API
        media_url = data['mediaUrl']  # Ex: /api/media/session-001_ABC123.jpg
        full_url = f'https://app.autowhats.com.br{media_url}'
        response = requests.get(full_url)
        binary_data = response.content
        
        # Determinar extensão
        mimetype = data.get('mediaMimetype', '')
        ext = mimetype.split('/')[1] if '/' in mimetype else 'bin'
        filename = data.get('mediaFilename') or f"midia_{int(time.time())}.{ext}"
        
        # Salvar arquivo
        with open(f"uploads/{filename}", 'wb') as f:
            f.write(binary_data)
        
        print(f"Mídia recebida: {filename}")
    
    return jsonify({'success': True}), 200

if __name__ == '__main__':
    os.makedirs('uploads', exist_ok=True)
    app.run(port=3001)

Exemplo de Webhook (PHP):

 true]);
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid payload']);
}
?>

🔧 Endpoints de Manutenção

Endpoints administrativos para gerenciar e manter a API. Requerem API key master.

{
  "daysOld": 30  // Padrão: 30 dias
}

{
  "success": true,
  "message": "Limpeza concluída",
  "cleaned": 5,      // Número de sessões removidas
  "errors": 0,        // Número de erros
  "total": 5          // Total de sessões encontradas
}

{
  "success": true,
  "total": 3,
  "sessions": [
    {
      "sessionId": "minha-sessao-001",
      "status": "connected",
      "inMemory": true,
      "hasFiles": true,
      "hasData": true,
      "messageCount": 150,
      "created_at": "2024-11-27T10:00:00.000Z",
      "last_activity": "2024-11-28T10:30:00.000Z",
      "disconnected_at": null,
      "webhook_url": "https://meusite.com/webhook"
    }
  ]
}

{
  "success": true,
  "message": "Sincronização concluída",
  "synced": 2  // Número de sessões sincronizadas
}

{
  "success": true,
  "message": "Limpeza concluída",
  "cleaned": 1  // Número de sessões removidas
}

💻 Exemplos de Uso

// Criar uma sessão (ou reutilizar se já existir)
const response = await fetch('https://app.autowhats.com.br/api/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sua_api_key_aqui'
  },
  body: JSON.stringify({
    sessionId: 'minha-sessao-001',
    webhookUrl: 'https://meusite.com/webhook'
  })
});

const data = await response.json();
console.log(data);
// Se data.existing === true, a sessão foi reutilizada
// Se não, uma nova sessão foi criada

// Obter QR Code
const qrResponse = await fetch('https://app.autowhats.com.br/api/sessions/minha-sessao-001/qr', {
  headers: {
    'X-API-Key': 'sua_api_key_aqui'
  }
});

const qrData = await qrResponse.json();
// Use qrData.qr em uma tag <img>
document.getElementById('qrcode').src = qrData.qr;

// Enviar mensagem
const messageResponse = await fetch('https://app.autowhats.com.br/api/messages/text', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sua_api_key_aqui'
  },
  body: JSON.stringify({
    sessionId: 'minha-sessao-001',
    to: '5571991460801',
    message: 'Olá! Esta é uma mensagem de teste.'
  })
});

const messageData = await messageResponse.json();
console.log('Mensagem enviada:', messageData);

# Criar sessão
curl -X POST https://app.autowhats.com.br/api/sessions \
  -H "X-API-Key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "minha-sessao-001",
    "webhookUrl": "https://meusite.com/webhook"
  }'

# Obter QR Code
curl -X GET https://app.autowhats.com.br/api/sessions/minha-sessao-001/qr \
  -H "X-API-Key: sua_api_key_aqui"

# Enviar mensagem
curl -X POST https://app.autowhats.com.br/api/messages/text \
  -H "X-API-Key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "minha-sessao-001",
    "to": "5571991460801",
    "message": "Olá! Esta é uma mensagem de teste."
  }'

import requests

API_BASE = "https://app.autowhats.com.br/api"
API_KEY = "sua_api_key_aqui"
headers = {"X-API-Key": API_KEY}

# Criar sessão
response = requests.post(
    f"{API_BASE}/sessions",
    headers=headers,
    json={
        "sessionId": "minha-sessao-001",
        "webhookUrl": "https://meusite.com/webhook"
    }
)
print(response.json())

# Obter QR Code
qr_response = requests.get(
    f"{API_BASE}/sessions/minha-sessao-001/qr",
    headers=headers
)
qr_data = qr_response.json()
print("QR Code:", qr_data["qr"])

# Enviar mensagem
message_response = requests.post(
    f"{API_BASE}/messages/text",
    headers=headers,
    json={
        "sessionId": "minha-sessao-001",
        "to": "5571991460801",
        "message": "Olá! Esta é uma mensagem de teste."
    }
)
print(message_response.json())

$apiBase = "https://app.autowhats.com.br/api";
$apiKey = "sua_api_key_aqui";

$headers = [
    "X-API-Key: " . $apiKey,
    "Content-Type: application/json"
];

// Criar sessão
$ch = curl_init($apiBase . "/sessions");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "sessionId" => "minha-sessao-001",
    "webhookUrl" => "https://meusite.com/webhook"
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

// Enviar mensagem
$ch = curl_init($apiBase . "/messages/text");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "sessionId" => "minha-sessao-001",
    "to" => "5571991460801",
    "message" => "Olá! Esta é uma mensagem de teste."
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

📊 Códigos de Status HTTP