Build with Engage

Quickstart

From nothing to a WhatsApp message triggered by your own code. Roughly ten minutes, and every step is copy-pasteable.

You need a workspace with a connected WhatsApp channel and at least one enabled workflow. Both are set up in the dashboard — this page covers the part your code does.

1. Issue an API key

In the dashboard, go to API keys and issue one. Name it after the system that will use it — orders-service, not key 1 — because the name is what you will read when deciding whether revoking it breaks anything.

2. Check that it works

curl https://api.engentra.io/v1/customers \
  -H "X-API-Key: $ENGAGE_API_KEY"

A 200 with a page of customers — possibly an empty one — means the key is live and scoped to your workspace. A 401 means the key is wrong or revoked.

3. Record an event

This is the call your system makes. Everything else is configuration.

curl -X POST https://api.engentra.io/v1/events \
  -H "X-API-Key: $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+2348012345678",
    "name": "Ada Obi",
    "type": "price.quoted",
    "data": { "item": "50kg rice", "amount": "62000" },
    "idempotencyKey": "quote-8821"
  }'

{
  "event": {
    "id": "9f1c...",
    "customerId": "7f92...",
    "type": "price.quoted",
    "source": "api",
    "data": { "item": "50kg rice", "amount": "62000" },
    "idempotencyKey": "quote-8821",
    "createdAt": "2026-09-13T14:22:10.412Z"
  },
  "recorded": true,
  "customerCreated": true,
  "matchedWorkflows": 1
}

4. Read the three flags before anything else

The response tells you whether the integration is actually wired up. These three fields exist because each one turns a silent misunderstanding into something visible on the first call.

matchedWorkflows — how many enabled workflows are waiting on this event type. Zero is the field's reason for existing. Event types are free text, so order_created sent to a workspace whose workflow triggers on order.created stores perfectly and does nothing, forever, with no error anywhere. If you see zero and expected otherwise, compare the two strings character by character.

customerCreated — whether this call enrolled a new person. If you meant to reach an existing customer and this says true, your phone formatting does not match what is already stored. See Customers.

recorded — false means an idempotency key matched something already stored and this call changed nothing. An integration seeing false every time has a key it is not varying, and would otherwise never find out.

5. Watch it happen

If matchedWorkflows was at least one, a workflow run has started. Most workflows wait — that is the point of them — so the message goes out when the delay elapses, not now. Open the conversation in the dashboard to watch it arrive.