Evolution API WhatsApp SDK

SDK oficial para integração com Evolution API WhatsApp. Envie mensagens WhatsApp facilmente em qualquer aplicação JavaScript/TypeScript.

🚀 Instalação

npm install @geovannev/evolution-whatsapp-sdk

📖 Uso Rápido

Configuração Inicial

const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'seu-tenant-id',
  apiKey: 'sua-api-key'
});

Enviar Mensagem

// Enviar mensagem simples
const message = await whatsapp.sendMessage({
  to: '5583998057011',
  message: 'Olá! Esta é uma mensagem de teste.'
});

console.log('Mensagem enviada:', message.id);

Criar Sessão com QR Code

// Criar nova sessão
const session = await whatsapp.createSession({
  name: 'Minha Sessão'
});

// Obter QR Code
const qrCode = await whatsapp.getQRCode(session.id);
console.log('QR Code:', qrCode); // Data URL base64

Criar Sessão com Pairing Code

// Criar sessão com pairing code
const session = await whatsapp.createSession({
  name: 'Minha Sessão',
  usePairingCode: true,
  phoneNumber: '5583998057011'
});

console.log('Código de pareamento:', session.pairingCode);

Listar Sessões

const sessions = await whatsapp.listSessions();

sessions.forEach(session => {
  console.log(`${session.name}: ${session.status}`);
});

Verificar Status da Sessão

const session = await whatsapp.getSession('session-id');

if (session.status === 'CONNECTED') {
  console.log('Sessão conectada!');
} else {
  console.log('Status:', session.status);
}

Listar Mensagens

const messages = await whatsapp.listMessages('session-id');

messages.forEach(msg => {
  console.log(`${msg.from}: ${msg.body}`);
});

Deletar Sessão

await whatsapp.deleteSession('session-id');
console.log('Sessão deletada');

🎯 Exemplos Completos

Sistema de Agendamento

const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

async function enviarLembrete(cliente) {
  try {
    await whatsapp.sendMessage({
      to: cliente.telefone,
      message: `Olá ${cliente.nome}! Lembrete: você tem consulta amanhã às ${cliente.horario}.`
    });
    console.log(`Lembrete enviado para ${cliente.nome}`);
  } catch (error) {
    console.error('Erro ao enviar lembrete:', error.message);
  }
}

// Enviar lembretes
const clientes = [
  { nome: 'João', telefone: '5583998057011', horario: '14:00' },
  { nome: 'Maria', telefone: '5583998057012', horario: '15:30' }
];

for (const cliente of clientes) {
  await enviarLembrete(cliente);
}

Sistema de Prospecção

const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

async function enviarProspeccao(leads) {
  for (const lead of leads) {
    try {
      await whatsapp.sendMessage({
        to: lead.telefone,
        message: `Olá! Temos uma oferta especial para você: ${lead.oferta}`
      });
      
      console.log(`Mensagem enviada para ${lead.nome}`);
      
      // Aguardar 2 segundos entre mensagens
      await new Promise(resolve => setTimeout(resolve, 2000));
    } catch (error) {
      console.error(`Erro ao enviar para ${lead.nome}:`, error.message);
    }
  }
}

const leads = [
  { nome: 'Cliente 1', telefone: '5583998057011', oferta: '50% de desconto' },
  { nome: 'Cliente 2', telefone: '5583998057012', oferta: 'Frete grátis' }
];

enviarProspeccao(leads);

Integração com Express

const express = require('express');
const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const app = express();
app.use(express.json());

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

// Endpoint para enviar mensagem
app.post('/send-message', async (req, res) => {
  try {
    const { to, message } = req.body;
    
    const result = await whatsapp.sendMessage({ to, message });
    
    res.json({ success: true, messageId: result.id });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

// Endpoint para criar sessão
app.post('/create-session', async (req, res) => {
  try {
    const { name } = req.body;
    
    const session = await whatsapp.createSession({ name });
    const qrCode = await whatsapp.getQRCode(session.id);
    
    res.json({ success: true, sessionId: session.id, qrCode });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

app.listen(4000, () => {
  console.log('Servidor rodando na porta 4000');
});

📚 API Reference

new EvolutionAPI(config)

Cria uma nova instância do SDK.

Parâmetros:

• config.baseURL (string): URL base da API
• config.tenantId (string): ID do tenant
• config.apiKey (string): Chave de API

sendMessage(options)

Envia uma mensagem de texto.

Parâmetros:

• options.to (string): Número do destinatário (formato: 5583998057011)
• options.message (string): Texto da mensagem
• options.sessionId (string, opcional): ID da sessão específica

Retorna: Promise<Message>

createSession(options)

Cria uma nova sessão WhatsApp.

Parâmetros:

• options.name (string): Nome da sessão
• options.usePairingCode (boolean, opcional): Usar pairing code
• options.phoneNumber (string, opcional): Número para pairing code

Retorna: Promise<Session>

listSessions()

Lista todas as sessões.

Retorna: Promise<Session[]>

getSession(sessionId)

Obtém uma sessão específica.

Parâmetros:

• sessionId (string): ID da sessão

Retorna: Promise<Session>

getQRCode(sessionId)

Obtém o QR Code de uma sessão.

Parâmetros:

• sessionId (string): ID da sessão

Retorna: Promise<string> (Data URL base64)

deleteSession(sessionId)

Deleta uma sessão.

Parâmetros:

• sessionId (string): ID da sessão

Retorna: Promise<void>

listMessages(sessionId)

Lista mensagens de uma sessão.

Parâmetros:

• sessionId (string): ID da sessão

Retorna: Promise<Message[]>

🔧 TypeScript

O SDK inclui definições de tipos TypeScript:

import { EvolutionAPI, SendMessageOptions, Session } from 'evolution-whatsapp-sdk';

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

const options: SendMessageOptions = {
  to: '5583998057011',
  message: 'Olá!'
};

const message = await whatsapp.sendMessage(options);

💡 Dicas Importantes

• Aguarde 1-2 segundos entre mensagens para evitar bloqueios
• Use variáveis de ambiente para armazenar credenciais
• Implemente tratamento de erros adequado
• Monitore o status das sessões regularmente

📝 Licença

MIT

🤝 Suporte

Para suporte, abra uma issue no GitHub ou entre em contato.

🔗 Links

• NPM Package
• GitHub Repository
• Documentation