API Reference · Endpoints

Conversations

List conversations, read message history, and find every conversation that belongs to the same customer.

A conversation (also called a chat) is one thread between a customer and your workspace on one channel. The first two endpoints are part of the public API and use your API key. The contact 360° helpers below them are dashboard endpoints and need a signed-in session token.

EndpointAuthPermission
GET /api/v1/conversationsX-API-Keyread
GET /api/v1/conversations/:chatId/messagesX-API-Keyread
GET /api/chats/:id/relatedBearer session token-
GET /api/chats/ltv-statsBearer session token-

List conversations

GET/api/v1/conversationsPaginated conversations, most recently updated first

GET /api/v1/chats is an alias with the same parameters and response.

ParameterTypeRequiredDescription
pagenumberoptionalPage number. Default 1.
limitnumberoptionalResults per page. Default 50, max 100.
statusstringoptionalFilter by status: open, assigned, resolved or closed.
platformstringoptionalFilter by channel: whatsapp, facebook, instagram, telegram, tiktok, widget, gmail, email, slack or voice.
visitorIdstringoptionalScope to one website-widget visitor. Matches the visitor's current chat and any merged visitor ids, and limits results to widget chats unless you also pass platform.
externalUserIdstringoptionalOnly chats whose widget identity has this user id (set with the widget's identify()).
emailstringoptionalOnly chats whose stored identity has this email.
customData.<key>stringoptionalMatch a custom identity field, for example customData.vendorId=abc. Repeat for several keys.
curl "https://inboxi.app/api/v1/conversations?status=open&limit=10" \
  -H "X-API-Key: inx_live_your_api_key"
json
{
  "success": true,
  "data": [
    {
      "id": 42,
      "customerName": "Ahmed Hassan",
      "phone": "201012345678",
      "platform": "whatsapp",
      "status": "open",
      "unreadCount": 2,
      "lastMessageAt": "2026-03-18T12:00:00.000Z",
      "lastMessagePreview": "Hello, I need help",
      "createdAt": "2026-03-01T09:15:00.000Z",
      "metadata": { },
      "externalUserId": null,
      "email": null,
      "customData": null,
      "baseVisitorId": null
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 37, "totalPages": 4 }
}

externalUserId, email, customData and baseVisitorId are copied out of metadata for convenience; they are filled for widget visitors you identified.

Scope widget requests to one visitor
If you call this endpoint on behalf of a single website visitor, always pass ?visitorId=…. Without it the response lists every conversation in the workspace.
bash
# Only this visitor's chats
curl "https://inboxi.app/api/v1/conversations?visitorId=${VISITOR_ID}&limit=50" \
  -H "X-API-Key: inx_live_your_api_key"

# Chats of one of your users, tagged with a vendor id
curl "https://inboxi.app/api/v1/conversations?externalUserId=u_12345&customData.vendorId=abc" \
  -H "X-API-Key: inx_live_your_api_key"

How widget visitors and identities are merged is explained in Widget identity & merge.

Get messages

GET/api/v1/conversations/:chatId/messagesMessage history of one conversation, newest first
ParameterTypeRequiredDescription
chatIdnumberrequiredPath parameter: the conversation id.
pagenumberoptionalPage number. Default 1.
limitnumberoptionalResults per page. Default 50, max 100.
curl "https://inboxi.app/api/v1/conversations/42/messages?limit=20" \
  -H "X-API-Key: inx_live_your_api_key"
json
{
  "success": true,
  "data": [
    {
      "id": 9876,
      "content": "Hello, I need help",
      "status": "received",
      "timestamp": "2026-03-18T12:00:00.000Z",
      "metadata": { }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 64, "totalPages": 4 }
}

Returns 404 with "error": "Conversation not found" if the chat is not in your workspace.

GET/api/chats/:id/relatedEvery chat that belongs to the same person

Auth: Bearer session token. Returns every conversation in your workspace that belongs to the same real person as the given chat, matched by phone, the stored real phone, email and externalUserId. A customer who wrote on WhatsApp and through the website widget comes back as one list.

ParameterTypeRequiredDescription
idnumberrequiredPath parameter: any conversation id of that person.
curl "https://inboxi.app/api/chats/42/related" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
json
{
  "success": true,
  "baseChatId": 42,
  "identityKeys": {
    "phone": "201001234567",
    "realPhone": "201001234567",
    "email": "ahmed@example.com",
    "externalUserId": null
  },
  "data": [
    { "id": 42, "platform": "whatsapp", "customerName": "Ahmed", "status": "open", "unreadCount": 0, "lastMessageAt": "...", "assignedAgent": null },
    { "id": 89, "platform": "widget", "customerName": "Ahmed", "status": "open", "unreadCount": 2, "lastMessageAt": "...", "assignedAgent": { "id": 3, "name": "Sara" } }
  ]
}

Each item also includes phone, profilePicUrl, lastMessagePreview, metadata, createdAt and hostNumber. The list is ordered by most recent message. Returns 404 if the base chat is not in your workspace.

Lifetime value stats

GET/api/chats/ltv-statsOrder count and total spend per customer phone

Auth: Bearer session token. Aggregates the orders of your workspace store by customer phone (digits only). It is a single aggregate query, safe to call when rendering a contact list.

curl "https://inboxi.app/api/chats/ltv-stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
json
{
  "success": true,
  "data": {
    "201001234567": { "orderCount": 5, "totalSpent": 2340.5, "lastOrderAt": "2026-05-01T10:12:00.000Z" },
    "201009876543": { "orderCount": 1, "totalSpent": 120, "lastOrderAt": "2026-04-15T08:40:00.000Z" }
  }
}

data is empty when the workspace has no orders. Both /api/chats endpoints answer 403 MODULE_DISABLED if the Inbox module is turned off for the workspace.