Integration guide

The autopilot reasons entirely over data you send EngageApp: who your contacts are and what they do. This guide covers the developer-side work — identifying contacts, emitting the right events, mapping them to the canonical behaviors the autopilot understands, and verifying the whole thing before you switch autonomy on. For a full worked example end to end, see the per-industry guides linked at the bottom.

How it fits together

1. Your systems send contacts and events to EngageApp.
2. During activation you map each of your event names onto a canonical behavior.
3. The autopilot classifies contacts, detects opportunities, and generates campaigns from those behaviors.

The single most important idea: the autopilot never guesses what your events mean. It only acts on behaviors you have explicitly mapped. Anything unmapped is ignored — which also means you can start with the required behaviors and add optional ones later.

Prerequisites

• A secret API key (df_…) for server-side ingestion — create one under Settings → API keys (see API keys).
• At least one connected channel the autopilot can send through.
• A stable external ID per user — your own primary key for that person. Everything ties back to it.

Step 1 — Identify your contacts

Upsert the people you want the autopilot to reason about, keyed by your external_id. Send whatever traits you have — at minimum an email or phone so a channel can reach them.

curl https://api.engageapp.xyz/api/v1/public/contacts \
  -H "X-API-Key: df_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "external_id": "user_8891",
        "email": "[email protected]",
        "phone": "+2348012345678",
        "first_name": "Ada",
        "last_name": "Okoro"
      }
    ]
  }'

You can also identify a contact inline on an event (below) by including the same fields — handy when your event pipeline is the only place you have the data. See Contacts for the full model.

Step 2 — Send behavioral events

Emit an event whenever a contact does something meaningful. Batch them from your backend to POST /api/v1/public/events. Each event needs an event_name and the external_id of the contact; properties and occurred_at are optional but recommended.

curl https://api.engageapp.xyz/api/v1/public/events \
  -H "X-API-Key: df_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "external_id": "user_8891",
        "event_name": "order_completed",
        "occurred_at": "2026-07-10T09:24:00Z",
        "properties": { "amount": 14500, "currency": "NGN", "items": 3 }
      }
    ]
  }'

The response is { "ingested": 1 }. Send events as they happen in production; you can also backfill history by setting "imported": true, which stores the events for classification without retroactively firing any existing automation.

What to instrument

You don't need dozens of events — you need the handful that map to the canonical behaviors your lifecycle model uses. Concretely, per contact, make sure you can answer:

• When did they join? (acquisition)
• When did they reach the key milestone? (conversion — the purchase, activation, subscription, funded account, first order…)
• When were they last active? (activity — the recurring action that shows they're still around)
• Optionally: a high-intent pre-conversion signal, and an explicit cancel signal.

Step 3 — Map events to canonical behaviors

In the activation wizard, pick your lifecycle model and map each canonical behavior it asks for to one of your real event names. The behaviors are grouped by the role they play:

Role          Canonical behaviors                 Example your-event mapping
-----------   ---------------------------------   --------------------------
acquisition   signed_up, registered,              signed_up  → "account_created"
              started_trial
conversion    activated, purchased, subscribed,   purchased  → "order_completed"
              funded_account, first_transaction,
              placed_first_order
activity      logged_in, feature_used,            placed_order → "order_completed"
              viewed_product, content_consumed,
              transacted, placed_order
intent        added_to_cart, contacted_seller     added_to_cart → "checkout_started"
churn         subscription_canceled               subscription_canceled → "plan_cancelled"

Required behaviors (typically acquisition, conversion, and activity) must be mapped for classification to run. Optional ones (intent, churn) unlock extra opportunities when present and are skipped when blank. See lifecycle classification for which behaviors each model asks for.

Step 4 — Connect a channel

The autopilot can only send through channels you've connected and selected. Connect at least one — email, SMS, WhatsApp, push, or in-app — then choose the participating channels in the wizard. Existing frequency caps, quiet hours, and suppressions continue to apply.

Step 5 — Activate

Finish activation, choosing your autonomy mode and guardrails. Start in review required so you can inspect what it proposes before anything sends.

Step 6 — Verify

1. Open the Events page and confirm your events are arriving with the names and properties you expect.
2. On the autopilot dashboard, click Classify now and check the lifecycle distribution — contacts should spread across stages that make sense.
3. Click Detect opportunities and review the queue. Each opportunity shows a plain-language rationale and audience size.
4. Approve one, open the generated campaign in the flow builder, and confirm it targets the right micro-segment through your chosen channel.

Once the drafts look right, widen your guardrails or switch to auto-execute.

Worked examples by industry

Each guide picks a representative business and shows the exact events, mappings, resulting stages, and campaigns:

• SaaS — a team collaboration tool (Slack-style).
• E-commerce — an online retailer (Konga-style).
• Marketplace — a classifieds marketplace (Jiji-style).
• Subscription / Media — a streaming service (Showmax-style).
• Fintech / Neobank — a digital bank (Kuda-style).
• On-demand / Delivery — a shared-mobility service (Shuttlers-style).