📱 Integrando Evolution API (WhatsApp)

version: "3.9"

services:
  evolution:
    image: atendai/evolution-api:latest
    container_name: evolution_api
    restart: always
    ports:
      - "8080:8080"
    environment:
      AUTHENTICATION_API_KEY: ${EVOLUTION_API_KEY}
      DATABASE_ENABLED: "true"
      DATABASE_PROVIDER: postgresql
      DATABASE_CONNECTION_URI: postgresql://evo:${DB_PASS}@postgres:5432/evolution
      REDIS_ENABLED: "true"
      REDIS_URI: redis://redis:6379
      WEBHOOK_GLOBAL_URL: ${WEBHOOK_URL}
      WEBHOOK_GLOBAL_ENABLED: "true"
      QRCODE_LIMIT: "30"
    depends_on:
      - postgres
      - redis
    volumes:
      - evolution_instances:/evolution/instances

  postgres:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_USER: evo
      POSTGRES_PASSWORD: ${DB_PASS}
      POSTGRES_DB: evolution
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U evo"]
      interval: 10s

  redis:
    image: redis:7-alpine
    restart: always
    volumes:
      - redis_data:/data

volumes:
  evolution_instances:
  postgres_data:
  redis_data:

EVOLUTION_API_KEY=troque-isso-por-uuid-forte
DB_PASS=outro-uuid-forte
WEBHOOK_URL=https://seu-app.convex.site/webhooks/evolution

🚀 Subir e validar

# subir
docker compose up -d

# verificar saúde
curl http://localhost:8080/

# logs em tempo real
docker compose logs -f evolution

# parar tudo
docker compose down

# reset completo (apaga sessões)
docker compose down -v

🔄 Ciclo de vida de uma instância

📋 Boas práticas pra não cair

🌊 Fluxo do webhook

import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { internal } from "./_generated/api";

const http = httpRouter();

http.route({
  path: "/webhooks/evolution",
  method: "POST",
  handler: httpAction(async (ctx, req) => {
    // 1. valida segredo no header
    const auth = req.headers.get("apikey");
    if (auth !== process.env.EVOLUTION_API_KEY) {
      return new Response("unauthorized", { status: 401 });
    }

    const body = await req.json();
    if (body.event !== "messages.upsert") return new Response("ok");

    const msg = body.data;
    if (msg.key.fromMe) return new Response("ok"); // ignora as nossas

    // 2. idempotência: se já processei este id, sai
    const existing = await ctx.runQuery(internal.messages.byExternalId, {
      externalId: msg.key.id,
    });
    if (existing) return new Response("ok");

    // 3. resolve contato e conversa
    const phone = msg.key.remoteJid.split("@")[0];
    const { contactId, conversationId } = await ctx.runMutation(
      internal.contacts.upsertAndOpen,
      { instanceName: body.instance, phone, name: msg.pushName }
    );

    // 4. grava mensagem
    await ctx.runMutation(internal.messages.create, {
      conversationId,
      externalId: msg.key.id,
      direction: "inbound",
      sender: "contact",
      body: msg.message?.conversation ?? "[mídia]",
      sentAt: msg.messageTimestamp * 1000,
    });

    // 5. agenda agente IA
    await ctx.scheduler.runAfter(0, internal.ai.respond, { conversationId });

    return new Response("ok");
  }),
});

export default http;

type SendPayload =
  | { kind: "text"; text: string }
  | { kind: "image"; url: string; caption?: string }
  | { kind: "audio"; url: string }
  | { kind: "document"; url: string; filename: string };

export async function sendMessage(
  instanceName: string,
  to: string,
  payload: SendPayload
) {
  const base = process.env.EVOLUTION_BASE_URL!;
  const headers = {
    "Content-Type": "application/json",
    apikey: process.env.EVOLUTION_API_KEY!,
  };

  const number = to.replace(/\D/g, "") + "@s.whatsapp.net";

  const routes = {
    text:     { path: "sendText",     body: { number, text: (payload as any).text } },
    image:    { path: "sendMedia",    body: { number, mediatype: "image",
                  media: (payload as any).url, caption: (payload as any).caption } },
    audio:    { path: "sendWhatsAppAudio", body: { number, audio: (payload as any).url } },
    document: { path: "sendMedia",    body: { number, mediatype: "document",
                  media: (payload as any).url, fileName: (payload as any).filename } },
  } as const;

  const route = routes[payload.kind];
  const res = await fetch(`${base}/message/${route.path}/${instanceName}`, {
    method: "POST", headers, body: JSON.stringify(route.body),
  });

  if (!res.ok) throw new Error(`evolution ${res.status}: ${await res.text()}`);
  return res.json();
}

{
  "number": "5511987654321@s.whatsapp.net",
  "text": "Olá Ana, posso te confirmar a reunião amanhã às 14h?"
}

⚖️ Limites e boas práticas