API Reference · Basics

API Reference

Every Inboxi endpoint with its parameters, request examples, response shapes and errors. Start here for the base URL, authentication, rate limits and conventions shared by all endpoints.

The Inboxi Platform API lets your own systems (a learning platform, a CRM, an online store, a booking tool) send WhatsApp messages, push data into Inboxi, read conversations and receive real-time events. This page covers what every endpoint has in common. Each endpoint group then has its own page with copy-paste examples in cURL, JavaScript and Python.

Base URL

All requests go to the Inboxi host over HTTPS. The public, versioned API lives under /api/v1:

text

https://inboxi.app/api/v1

A few endpoints documented here sit outside /api/v1 because they are shared with the Inboxi dashboard: WhatsApp templates (/api/whatsapp/templates), the contact 360° helpers (/api/chats/…) and the public plan map (/api/subscriptions/features-map). They use a different authentication method, described below.

Authentication

Which credential you send depends on the endpoint group:

Endpoint group	Credential	Header
`/api/v1/*`	X-API-Key	`X-API-Key: inx_live_…`
`/api/whatsapp/templates/*`	Bearer session token	`Authorization: Bearer <access token>`
`/api/chats/:id/related`	Bearer session token	`Authorization: Bearer <access token>`
`/api/chats/ltv-stats`	Bearer session token	`Authorization: Bearer <access token>`
`/api/subscriptions/features-map`	No auth

API keys

Create API keys in Settings › Developer Hub › API Keys. A key looks like inx_live_… and is sent in the X-API-Key header on every /api/v1 request. The full key and its signing secret (sk_live_…) are shown once, when you create the key.

curl "https://inboxi.app/api/v1/conversations?limit=10" \
  -H "X-API-Key: inx_live_your_api_key"

Keep keys on your server

An API key acts for your whole workspace. Never ship it in browser code or a mobile app bundle. Call the API from your backend and keep the key in an environment variable.

Each key carries a list of permissions (read, write, webhooks, widget, external_data, or * for everything). A new key gets read, write, webhooks, widget and external_data. Each endpoint page lists the permission it needs; Plans & features map explains how permissions and plans combine.

Session tokens

The template and contact-360° endpoints are the same ones the Inboxi dashboard calls. They expect the short-lived access token of a signed-in Inboxi user in Authorization: Bearer …; an X-API-Key header is not accepted there. When the token expires the API answers 401 with code TOKEN_EXPIRED and you need a fresh token. For unattended server integrations, prefer the /api/v1 endpoints.

Requests and content type

Send request bodies as JSON with Content-Type: application/json.
Responses are always JSON.
Path parameters are shown as :name (for example /api/v1/webhooks/:id).
Phone numbers are accepted with or without +, spaces or dashes; Inboxi keeps the digits only (for example +20 101 234 5678 becomes 201012345678).
Timestamps are ISO 8601 strings in UTC.

Response envelope

Every response has a boolean success. Successful responses put the result in data:

json

{
  "success": true,
  "data": { "chatId": 42, "messageId": 9876, "to": "201012345678", "status": "sent" }
}

List endpoints add a pagination object next to data. A few endpoints return their result fields at the top level instead of under data (for example the bulk push returns created, updated and errors); each endpoint page shows the exact shape. Failed requests return success: false with an error; see Errors.

Pagination

List endpoints are paginated with two query parameters:

Parameter	Type	Required	Description
`page`	number	optional	Page number, starting at 1. Default 1.
`limit`	number	optional	Items per page. Default 50. Capped at 100 for conversations, messages, contacts and webhook logs, and at 200 for external data.

json

{
  "success": true,
  "data": [ ... ],
  "pagination": { "page": 1, "limit": 50, "total": 128, "totalPages": 3 }
}

Results are ordered newest first. Keep requesting the next page until it reaches totalPages.

Rate limits

Each API key may make 60 requests per minute by default, counted in a fixed one-minute window. Every /api/v1 response carries the current state:

Header	Type	Required	Description
`X-RateLimit-Limit`	number	optional	Requests allowed per minute for this key.
`X-RateLimit-Remaining`	number	optional	Requests left in the current window.
`Retry-After`	number	optional	Only on 429 responses: seconds until the window resets.

Past the limit, the API answers 429 with { "success": false, "error": "Rate limit exceeded. Max 60 requests per minute." }. Wait for Retry-After seconds before retrying. Event triggers can also return 429 with code COOLDOWN_ACTIVE when an event has a per-recipient cooldown; see Events.

Versioning

The version is part of the path: /api/v1. Changes inside v1 are additive (new endpoints, new optional parameters, new response fields), so write clients that ignore fields they do not know. A breaking change would ship under a new path prefix. The dashboard-shared endpoints (/api/whatsapp/templates, /api/chats) are not versioned.