Proactive Messaging

Proactive messaging lets your backend trigger outbound messages to customers — order shipped notifications, reminders, follow-ups — with built-in guardrails.

Enable proactive messaging

# config.proactive.yaml
proactive:
  enabled: true
  daily_cap: 3
  dedup_window_hours: 24

Or point AELIO_CONFIG at the proactive profile.

Opt in a customer

curl -X POST https://your-server/proactive/opt-in \
  -H "Authorization: Bearer $AELIO_SDK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"customerExternalId": "user_abc123", "optIn": true}'

Send a proactive message

curl -X POST https://your-server/proactive \
  -H "Authorization: Bearer $AELIO_SDK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerExternalId": "user_abc123",
    "channel": "whatsapp",
    "content": "Your order #A123 has shipped!",
    "dedupKey": "ship-A123"
  }'

Guardrails

Check	Blocked reason
Feature disabled	"Proactive messaging is disabled"
Unknown customer	"Unknown customer"
No channel address	"No `channel` address"
Not opted in	"Customer has not opted in"
Duplicate	"Duplicate (dedupKey already sent)"
Daily cap	"Daily proactive limit reached"
WhatsApp 24h window	"Outside 24h window — a template message is required"

Use cases

Order status updates
Appointment reminders
Re-engagement after inactivity
Follow-up after support conversations

From your backend code

async function notifyOrderShipped(userId: string, orderId: string) {
  await fetch(`${AELIO_HTTP_URL}/proactive`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AELIO_SDK_SECRET}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerExternalId: userId,
      channel: 'web',
      content: `Great news! Your order ${orderId} has shipped.`,
      dedupKey: `ship-${orderId}`,
    }),
  });
}

Daemon follow-up

Enable background follow-up with config.followup.yaml:

daemon:
  enabled: true
  proactive_followup: true

The reflection daemon reviews sessions and can trigger proactive follow-ups automatically.