Evolution Api Management

All endpoints require header: apikey: $AUTHENTICATION_API_KEY

ECS Exec Commands

Container is BusyBox-based: no curl/wget. Use node -e for everything.

# Template for all ECS exec commands
aws ecs execute-command \
  --cluster "$CLUSTER" \
  --task "$TASK_ID" \
  --container EvolutionService \
  --interactive \
  --command 'node -e "...script..."'

Get task ID:

TASK_ID=$(aws ecs list-tasks --cluster "$CLUSTER" --service-name EvolutionService \
  --query 'taskArns[0]' --output text | awk -F/ '{print $NF}')

ECS exec output gotchas:

• Output always contains Starting session... and Cannot perform start session: EOF noise
• Use grep or tail to extract useful data
• Long outputs get truncated (~3KB). For large data: write to file inside container, read in chunks via base64
• Shell escaping through ECS exec is fragile. For complex payloads: base64-encode the JSON body, decode inside the node script

Instance Lifecycle

Create Instance with Webhook

// Body for POST /instance/create
{
  instanceName: 'alinhou-production',
  integration: 'WHATSAPP-BAILEYS',
  qrcode: true,
  rejectCall: false,
  groupsIgnore: true,
  alwaysOnline: false,
  readMessages: false,
  readStatus: false,
  syncFullHistory: false,
  webhook: {
    url: 'https://lambda-url/api/v1/webhook/evolution',
    byEvents: true,
    base64: false,
    events: ['MESSAGES_UPSERT'],
    headers: { jwt_key: 'YOUR_WEBHOOK_SECRET' }  // MUST have a value
  }
}

Update Webhook on Existing Instance

// POST /webhook/set/{instanceName}
// MUST wrap in "webhook" property
{
  webhook: {
    enabled: true,
    url: 'https://lambda-url/api/v1/webhook/evolution',
    webhookByEvents: true,
    webhookBase64: false,
    events: ['MESSAGES_UPSERT'],
    headers: { jwt_key: 'YOUR_WEBHOOK_SECRET' }
  }
}

QR Code Generation Workflow

1. Call /instance/connect/{name} - returns { code, base64, pairingCode }
2. The code field is the raw QR data string (~240 chars)
3. Generate QR locally: npx qrcode -o /tmp/qr.png "$CODE" or use require('qrcode').toDataURL()
4. Create HTML with embedded base64 image (no CDN dependency)
5. Copy to Windows: /mnt/c/Users/{user}/Downloads/
6. QR expires in ~45 seconds - be fast

Never try to pipe base64 image data through ECS exec - it gets truncated and corrupted.

Environment Isolation

The Problem

WhatsApp Baileys protocol enforces single connection per phone number. Staging + production competing = session conflict loop.

The Solution

In SST infra:

WHATSAPP_MOCK: $app.stage === 'production' ? 'false' : 'true',
EVOLUTION_INSTANCE_NAME: `alinhou-${$app.stage}`,