Developer Guide · Guides

Event messaging

Design WhatsApp messages once in the dashboard, then send them from your backend with one API call per event. Inboxi fills the variables, picks a session message or an approved template, and tracks delivery.

Event messaging separates what is said from when it is said. Your team writes the message for an event such as order.shipped in Settings › Automated Messages. Your developers only send the event name, the phone number and the data. Wording can change without a deploy, and WhatsApp's 24-hour rule is handled for you.

How it works

1. Your platform calls the trigger endpoint. Inboxi checks the event is active and required variables are present, then returns 202 with a logId.
2. A background worker renders the message and finds or creates the chat for that number.
3. If the customer messaged you in the last 24 hours, the session message is sent as normal text (with an optional URL button).
4. Otherwise Inboxi sends the Meta-approved template mapped to the event. The send method is recorded on the log.
5. The message appears in the inbox conversation like any other, so agents see exactly what the customer received.

Set up events in the dashboard

Open Settings › Automated Messages. If the list is empty, click Create System Events to add the built-in events. System events start switched off; you activate each one after configuring its message.

inboxi.app/settings/automated-messages

12345

The editor has four tabs:

inboxi.app/settings/automated-messages

12345

Built-in events

Optional fields (such as tracking_number, access_link, report_link) can also be sent and used in the message. Custom events must use lowercase letters, numbers, underscores and dots, are always prefixedcustom., and a workspace can have up to 50.

Trigger an event

curl -X POST https://inboxi.app/api/v1/events/trigger \
  -H "X-API-Key: $INBOXI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "enrollment.created",
    "phone": "201012345678",
    "data": {
      "student_name": "Ahmed Ali",
      "course_name": "Mathematics 101",
      "access_link": "https://academy.example.com/courses/101"
    }
  }'

{
  "success": true,
  "data": { "logId": 1042, "status": "queued" }
}

To know which events and fields are available without opening the dashboard, callGET /api/v1/events/messaging. It returns every active event with its requiredFields,optionalFields and full schema.

Scheduling

Add sendAt to send later, for example an appointment reminder the evening before:

{
  "event": "appointment.reminder",
  "phone": "201012345678",
  "data": { "customer_name": "Sara", "date": "2026-11-02", "time": "10:30" },
  "sendAt": "2026-11-01T17:00:00Z"
}

// Response
{ "success": true, "data": { "logId": 1043, "status": "scheduled", "scheduledAt": "2026-11-01T17:00:00Z" } }

• Scheduled sends are picked up by a periodic job once sendAt has passed, so expect delivery shortly after the exact time, not to the second.
• The 24-hour window is evaluated at send time, not when you scheduled it.
• Events marked sensitive (one-time codes) cannot be scheduled and return SCHEDULING_NOT_ALLOWED.

Check delivery status

{
  "success": true,
  "data": {
    "logId": 1042,
    "event": "enrollment.created",
    "phone": "201012345678",
    "status": "sent",
    "sendMethod": "template",
    "error": null,
    "processedAt": "2026-10-10T09:30:02.000Z",
    "createdAt": "2026-10-10T09:30:00.000Z"
  }
}

sendMethod tells you which path was used: session or session_interactive (inside the window, plain or with a URL button), template (approved template), or report_template (template linking to a generated report page). For real delivery confirmation subscribe to the message.delivered, message.read andmessage.failed webhooks.

The 24-hour window and template fallback

WhatsApp allows free-form messages only within 24 hours of the customer's last message. Outside that window, only templates pre-approved by Meta can be sent. Inboxi decides for you on every send: