WhatsApp Integration

Aelio supports WhatsApp through two approaches:

Built-in Meta adapter — configure credentials in config.yaml
Bring your own provider — use aelio.ingest() and aelio.onSend() from your SDK

Meta Cloud API (built-in)

Configuration

channels:
  whatsapp:
    enabled: true
    provider: meta
    phone_id: ${WA_PHONE_ID}
    token: ${WA_TOKEN}
    verify_token: ${WA_VERIFY_TOKEN}
    app_secret: ${WA_APP_SECRET}
    webhook_path: /wa/webhook

Environment variables

WA_PHONE_ID=your-phone-number-id
WA_TOKEN=your-access-token
WA_VERIFY_TOKEN=your-verify-token
WA_APP_SECRET=your-app-secret

Webhook setup

In Meta Developer Console, set webhook URL to https://your-server.com/wa/webhook
Set verify token to match WA_VERIFY_TOKEN
Subscribe to messages events

Flow

Customer sends WhatsApp message
  → Meta POST /wa/webhook
  → HMAC signature verify
  → parse message, dedup
  → inbound job queue
  → identity resolve
  → processTurn() (LLM + SDK tools)
  → outbound job
  → MetaWhatsAppSender
  → customer receives reply

Bring your own provider

For Twilio, Gupshup, 360dialog, or any other provider:

Server config

channels:
  whatsapp:
    enabled: true
    provider: sdk

SDK hooks

// Deliver replies through YOUR provider
aelio.onSend(async ({ channel, to, content }) => {
  await myProvider.messages.create({ to, body: content });
});

// In your webhook route
app.post('/my-whatsapp-webhook', (req, res) => {
  const { from, text } = myProvider.parse(req.body);
  aelio.ingest({ channel: 'whatsapp', from, text });
  res.sendStatus(200);
});

You own webhook parsing, signature verification, and delivery. Aelio handles identity, memory, LLM, safety, and reply generation.

24-hour messaging window

WhatsApp enforces a 24-hour window for free-form messages. Outside this window, only pre-approved template messages can be sent. Aelio's proactive messaging respects this constraint.

Test mode

With AELIO_TEST_MODE=1, a mock WhatsApp sender is used. Check sent messages:

curl http://localhost:3010/__test__/whatsapp/outbox

WhatsApp Integration

On this page