API Reference · Endpoints

Events

Trigger automated WhatsApp messages by event name, list the events your workspace has configured, and track each send.

Event messaging is the simplest way to send automated WhatsApp messages. You design the message once in Settings › Automated Messages; your platform then sends the event name, a phone number and the variables. Inboxi renders the message, checks the WhatsApp 24-hour window, falls back to an approved template when needed, and sends it. For the full walkthrough see Event messaging.

Your platform

POST /events/trigger with event, phone, data

202 + logId

Inboxi

Validates variables, logs and queues the send

worker

Message builder

Session message inside 24h, template outside

Cloud API

Delivered to the customer

Endpoint	Permission
`POST /api/v1/events/trigger`	`write`
`GET /api/v1/events/messaging`	`read`
`GET /api/v1/events/messaging/:logId/status`	`read`

Trigger an event

POST/api/v1/events/triggerSend an automated message

Validates the variables, logs the send and queues it. Returns 202 Accepted with a logId you can poll.

Parameter	Type	Required	Description
`event`	string	required	Event name, for example `enrollment.created` or `custom.homework_submitted`. The event must be active.
`phone`	string	required	Recipient with country code, for example `201012345678`. Non-digits are stripped.
`data`	object	optional	Variables for the message. Must include every field the event marks as required.
`variables`	object	optional	Alias of `data`. If both are sent, `data` wins.
`sendAt`	string	optional	ISO 8601 time to send later, for example `2026-03-20T10:00:00Z`. Not allowed for events marked sensitive.

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

Response: queued

json

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

Response: scheduled

When you pass sendAt, nothing is sent yet:

json

{
  "success": true,
  "data": { "logId": 2, "status": "scheduled", "scheduledAt": "2026-03-20T10:00:00Z" }
}

Errors

Status	error	When
400	`VALIDATION_ERROR`	`event` or `phone` missing, or `data` is not an object.
400	`EVENT_NOT_ACTIVE`	No active event with that name in your workspace.
400	`MISSING_FIELDS`	A required variable is missing; the message names them.
400	`SCHEDULING_NOT_ALLOWED`	`sendAt` was passed for a sensitive event.
429	`COOLDOWN_ACTIVE`	This event already went to this number within its cooldown.
500	`INTERNAL_ERROR`	Unexpected failure.

json

{
  "success": false,
  "error": "EVENT_NOT_ACTIVE",
  "message": "Event 'order.created' is not configured or not active"
}

A cooldown response also sets the Retry-After header and tells you which earlier send is still inside the window, so you can poll it instead of triggering again:

json

{
  "success": false,
  "error": "COOLDOWN_ACTIVE",
  "message": "A 'otp.code' message was already sent to this number 12s ago. Try again in 48s.",
  "retryAfter": 48,
  "logId": 311
}

The 24-hour window

WhatsApp only allows free-form messages within 24 hours of the customer's last message. Outside that window Inboxi sends the approved Meta template you attached to the event (in the event's template settings). Without one, the send fails and its status shows the error.

List messaging events

GET/api/v1/events/messagingActive events and their variables

Returns every active event in your workspace with the variables it expects, so your developers know exactly what to send.

curl "https://inboxi.app/api/v1/events/messaging" \
  -H "X-API-Key: inx_live_your_api_key"

json

{
  "success": true,
  "data": [
    {
      "event": "enrollment.created",
      "label": "New student enrollment",
      "description": "Sent when a student enrolls in a course",
      "category": "education",
      "isSystem": true,
      "requiredFields": ["student_name", "course_name"],
      "optionalFields": ["start_date", "access_link"],
      "schema": [
        { "key": "student_name", "label": "Student name", "type": "string", "required": true },
        { "key": "course_name", "label": "Course name", "type": "string", "required": true },
        { "key": "start_date", "label": "Start date", "type": "string", "required": false },
        { "key": "access_link", "label": "Access link", "type": "string", "required": false }
      ]
    }
  ]
}

Only events switched on in the dashboard appear. Labels and descriptions are the ones set in your workspace.

Check delivery status

GET/api/v1/events/messaging/:logId/statusStatus of one triggered event

Parameter	Type	Required	Description
`logId`	number	required	Path parameter: the `logId` returned by the trigger call.

curl "https://inboxi.app/api/v1/events/messaging/1/status" \
  -H "X-API-Key: inx_live_your_api_key"

json

{
  "success": true,
  "data": {
    "logId": 1,
    "event": "enrollment.created",
    "phone": "201012345678",
    "status": "sent",
    "sendMethod": "session",
    "error": null,
    "processedAt": "2026-03-19T10:30:02.000Z",
    "createdAt": "2026-03-19T10:30:00.000Z"
  }
}

Field	Values
`status`	`pending`, `queued`, `processing`, `sent`, `failed`, `scheduled`
`sendMethod`	`session` (free-form, inside 24h), `session_interactive` (with buttons), `template` (Meta template), `report_template` (report link template), or `null` before sending
`error`	Failure reason when `status` is `failed`, otherwise `null`

Returns 404 with "error": "NOT_FOUND" if the log does not exist in your workspace.

System events

Every workspace comes with these built-in events. They start switched off: open Settings › Automated Messages, write the message, attach a template, and activate.

Event	Category	Sent when	Required	Optional
`enrollment.created`	education	A student enrolled in a course	student_name, course_name	start_date, access_link
`enrollment.activated`	education	A subscription was activated	student_name, course_name	-
`enrollment.expired`	education	A subscription expired	student_name, course_name	expiry_date
`student.performance_report`	education	Performance report for a student	student_name, course_name	report_link, attendance_score, exam_score, homework_score, total_score, lessons
`order.created`	orders	A new order was placed	customer_name, order_number	total_amount
`order.confirmed`	orders	An order was confirmed	customer_name, order_number	-
`order.shipped`	orders	An order was shipped	customer_name, order_number	tracking_number
`order.delivered`	orders	An order was delivered	customer_name, order_number	-
`appointment.created`	appointments	An appointment was booked	customer_name, date, time	service_name
`appointment.reminder`	appointments	Reminder before an appointment	customer_name, date, time	-
`payment.received`	payments	A payment was received	customer_name, amount	currency
`payment.failed`	payments	A payment failed	customer_name, amount	-
`custom.notification`	general	Free-text notification	message	-

Custom events

Create your own events with + Custom Event in Settings › Automated Messages. Their names are prefixed with custom. automatically (for example custom.homework_submitted), and you define their variables. See Automated messages.