v2.3.7

🚀 Evolution API

API completa para integração com WhatsApp. Conecte seus sistemas de forma simples e segura.

API Online
Client: -
WhatsApp Web: -

🔐 Autenticação

Todas as requisições à API devem incluir uma chave de autenticação no header.

Header de Autenticação

HTTP Header
apikey: SUA_API_KEY_AQUI
💡 Dica: A API Key é configurada no arquivo .env através da variável AUTHENTICATION_API_KEY
Header Valor Obrigatório
apikey Sua chave de API ✅ Sim
Content-Type application/json ✅ Sim (para POST/PUT)

📱 Gerenciamento de Instâncias

Uma instância representa uma conexão com o WhatsApp. Você pode criar múltiplas instâncias para gerenciar diferentes números.

POST /instance/create

Cria uma nova instância do WhatsApp.

Request Body:

JSON
{
    "instanceName": "minha-instancia",
    "integration": "WHATSAPP-BAILEYS",
    "qrcode": true,
    "webhook": {
        "url": "https://seu-sistema.com/webhook",
        "byEvents": true,
        "events": [
            "MESSAGES_UPSERT",
            "CONNECTION_UPDATE",
            "QRCODE_UPDATED"
        ]
    }
}

Exemplo cURL:

Bash
curl -X POST "http://localhost:8080/instance/create" \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "minha-instancia",
    "integration": "WHATSAPP-BAILEYS",
    "qrcode": true
  }'
GET /instance/connect/{instanceName}

Obtém o QR Code para conectar uma instância ao WhatsApp.

Exemplo cURL:

Bash
curl -X GET "http://localhost:8080/instance/connect/minha-instancia" \
  -H "apikey: SUA_API_KEY"
GET /instance/connectionState/{instanceName}

Verifica o status de conexão de uma instância.

Resposta de Sucesso:

JSON
{
    "instance": {
        "instanceName": "minha-instancia",
        "state": "open"
    }
}
Estados possíveis: open (conectado), close (desconectado), connecting (conectando)
GET /instance/fetchInstances

Lista todas as instâncias cadastradas.

DELETE /instance/delete/{instanceName}

Remove uma instância permanentemente.

💬 Envio de Mensagens

Endpoints para enviar diferentes tipos de mensagens via WhatsApp.

POST /message/sendText/{instanceName}

Envia uma mensagem de texto simples.

Request Body:

JSON
{
    "number": "5511999999999",
    "text": "Olá! Esta é uma mensagem de teste.",
    "delay": 1200
}
⚠️ Importante: O número deve estar no formato internacional, sem caracteres especiais (apenas números). Ex: 5511999999999

Exemplo em JavaScript:

JavaScript
const response = await fetch('http://localhost:8080/message/sendText/minha-instancia', {
    method: 'POST',
    headers: {
        'apikey': 'SUA_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        number: '5511999999999',
        text: 'Olá! Esta é uma mensagem de teste.'
    })
});

const data = await response.json();
console.log(data);
POST /message/sendMedia/{instanceName}

Envia imagens, vídeos, áudios ou documentos.

Request Body:

JSON
{
    "number": "5511999999999",
    "mediatype": "image",
    "mimetype": "image/png",
    "caption": "Legenda da imagem",
    "media": "https://exemplo.com/imagem.png"
}
mediatype Descrição
image Imagens (PNG, JPG, etc.)
video Vídeos (MP4, etc.)
audio Áudios (MP3, OGG, etc.)
document Documentos (PDF, DOC, etc.)

📍 Localização

POST /message/sendLocation/{instance}

Envia uma localização no mapa.

👤 Contato

POST /message/sendContact/{instance}

Envia um cartão de contato.

🎤 Áudio (PTT)

POST /message/sendWhatsAppAudio/{instance}

Envia áudio como mensagem de voz.

📋 Lista

POST /message/sendList/{instance}

Envia uma mensagem com lista de opções.

🔘 Botões

POST /message/sendButtons/{instance}

Envia mensagem com botões interativos.

📊 Enquete

POST /message/sendPoll/{instance}

Envia uma enquete para votação.

👥 Gerenciamento de Grupos

Endpoints para criar e gerenciar grupos do WhatsApp.

POST /group/create/{instanceName}

Cria um novo grupo.

Request Body:

JSON
{
    "subject": "Nome do Grupo",
    "description": "Descrição do grupo",
    "participants": [
        "5511999999999",
        "5511888888888"
    ]
}

📋 Listar Grupos

GET /group/fetchAllGroups/{instance}

➕ Adicionar Participante

POST /group/updateParticipant/{instance}

🔗 Link do Grupo

GET /group/inviteCode/{instance}

🚪 Sair do Grupo

DELETE /group/leaveGroup/{instance}

🔔 Webhooks (Eventos)

Configure webhooks para receber notificações em tempo real sobre eventos do WhatsApp.

Configurar Webhook

POST /webhook/set/{instanceName}
JSON
{
    "webhook": {
        "enabled": true,
        "url": "https://seu-sistema.com/webhook",
        "byEvents": true,
        "base64": false,
        "events": [
            "MESSAGES_UPSERT",
            "MESSAGES_UPDATE",
            "CONNECTION_UPDATE",
            "QRCODE_UPDATED",
            "SEND_MESSAGE"
        ]
    }
}

Eventos Disponíveis

Evento Descrição
MESSAGES_UPSERT Nova mensagem recebida
MESSAGES_UPDATE Mensagem atualizada (lida, entregue, etc.)
CONNECTION_UPDATE Status da conexão alterado
QRCODE_UPDATED Novo QR Code gerado
SEND_MESSAGE Mensagem enviada com sucesso
CONTACTS_UPDATE Contato atualizado
GROUPS_UPSERT Grupo criado ou atualizado

Exemplo de Payload Recebido

JSON - Mensagem Recebida
{
    "event": "messages.upsert",
    "instance": "minha-instancia",
    "data": {
        "key": {
            "remoteJid": "5511999999999@s.whatsapp.net",
            "fromMe": false,
            "id": "3EB0..."
        },
        "pushName": "Nome do Contato",
        "message": {
            "conversation": "Olá, tudo bem?"
        },
        "messageType": "conversation",
        "messageTimestamp": 1705849200
    }
}

⚠️ Tratamento de Erros

A API retorna códigos HTTP padrão para indicar sucesso ou falha.

Código Status Descrição
200 OK Requisição bem-sucedida
201 Created Recurso criado com sucesso
400 Bad Request Dados inválidos na requisição
401 Unauthorized API Key inválida ou ausente
404 Not Found Instância ou recurso não encontrado
500 Internal Error Erro interno do servidor

Formato de Erro

JSON
{
    "status": 401,
    "error": "Unauthorized",
    "message": "Invalid API key"
}

📚 Exemplos de Integração

Exemplos práticos de como integrar seu sistema com a Evolution API.

Node.js / JavaScript

JavaScript
const API_URL = 'http://localhost:8080';
const API_KEY = 'SUA_API_KEY';

// Classe para gerenciar a API
class EvolutionAPI {
    constructor(apiUrl, apiKey) {
        this.apiUrl = apiUrl;
        this.headers = {
            'apikey': apiKey,
            'Content-Type': 'application/json'
        };
    }

    async createInstance(instanceName) {
        const response = await fetch(`${this.apiUrl}/instance/create`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({
                instanceName,
                integration: 'WHATSAPP-BAILEYS',
                qrcode: true
            })
        });
        return response.json();
    }

    async sendText(instanceName, number, text) {
        const response = await fetch(`${this.apiUrl}/message/sendText/${instanceName}`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ number, text })
        });
        return response.json();
    }

    async getConnectionState(instanceName) {
        const response = await fetch(`${this.apiUrl}/instance/connectionState/${instanceName}`, {
            headers: this.headers
        });
        return response.json();
    }
}

// Uso
const api = new EvolutionAPI(API_URL, API_KEY);

// Criar instância
const instance = await api.createInstance('meu-bot');

// Enviar mensagem
const result = await api.sendText('meu-bot', '5511999999999', 'Olá!');

Python

Python
import requests

API_URL = 'http://localhost:8080'
API_KEY = 'SUA_API_KEY'

headers = {
    'apikey': API_KEY,
    'Content-Type': 'application/json'
}

# Criar instância
def create_instance(instance_name):
    response = requests.post(
        f'{API_URL}/instance/create',
        headers=headers,
        json={
            'instanceName': instance_name,
            'integration': 'WHATSAPP-BAILEYS',
            'qrcode': True
        }
    )
    return response.json()

# Enviar mensagem de texto
def send_text(instance_name, number, text):
    response = requests.post(
        f'{API_URL}/message/sendText/{instance_name}',
        headers=headers,
        json={
            'number': number,
            'text': text
        }
    )
    return response.json()

# Exemplo de uso
instance = create_instance('meu-bot')
print(instance)

result = send_text('meu-bot', '5511999999999', 'Olá do Python!')
print(result)

PHP

PHP
<?php

$apiUrl = 'http://localhost:8080';
$apiKey = 'SUA_API_KEY';

function sendRequest($endpoint, $method = 'GET', $data = null) {
    global $apiUrl, $apiKey;
    
    $ch = curl_init($apiUrl . $endpoint);
    
    $headers = [
        'apikey: ' . $apiKey,
        'Content-Type: application/json'
    ];
    
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Enviar mensagem
function sendText($instanceName, $number, $text) {
    return sendRequest("/message/sendText/{$instanceName}", 'POST', [
        'number' => $number,
        'text' => $text
    ]);
}

// Exemplo de uso
$result = sendText('meu-bot', '5511999999999', 'Olá do PHP!');
print_r($result);

?>

Recebendo Webhooks (Node.js/Express)

JavaScript
const express = require('express');
const app = express();

app.use(express.json());

// Endpoint para receber webhooks
app.post('/webhook', (req, res) => {
    const { event, instance, data } = req.body;
    
    console.log(`Evento: ${event}`);
    console.log(`Instância: ${instance}`);
    
    switch (event) {
        case 'messages.upsert':
            // Nova mensagem recebida
            const message = data.message;
            const from = data.key.remoteJid;
            console.log(`Mensagem de ${from}:`, message);
            
            // Processar mensagem...
            break;
            
        case 'connection.update':
            // Status da conexão alterado
            console.log(`Status: ${data.state}`);
            break;
            
        case 'qrcode.updated':
            // Novo QR Code
            console.log('QR Code atualizado');
            break;
    }
    
    res.status(200).json({ received: true });
});

app.listen(3000, () => {
    console.log('Webhook server running on port 3000');
});