Skip to content

REST API v1 · Resource

Inbox

Read and update a conversation, add notes, mark it read, start a chat and fetch a message’s file.

API reference · Inbox

Endpoints

Paths are relative to https://fliok.com/api/v1. Each endpoint names the scope and the lowest key role it needs; a key without them gets 403 (see Authentication).

Inbox

7
  • GET/conversations/{id}One conversation, including whether the 24-hour free-form window is openScope conversations:read · viewer role or higher
  • PATCH/conversations/{id}Assign, prioritise, resolve or archive a conversationScope conversations:write · agent role or higher
  • GET/conversations/{id}/notesInternal notes on a conversation — never sent to the customerScope conversations:read · viewer role or higher
  • POST/conversations/{id}/notesAdd an internal noteScope conversations:write · agent role or higher
  • POST/conversations/{id}/readMark a chat read, as opening it in the inbox does — unread to 0, and a read receipt (blue ticks) for the customerScope conversations:write · agent role or higher
  • POST/conversationsStart a WhatsApp chat with one person — by contact id or number — with an approved template, through every send gate. lookup: true only finds the existing chatScope messages:send · agent role or higher
  • GET/messages/{id}/mediaA five-minute download link for the file a message carries (by our id or wamid). Only the workspace’s own stored filesScope messages:read · viewer role or higher

Request bodies

What these endpoints take, field by field. A body that doesn’t match answers 400 naming the field.

GET /messages · GET /contacts · GET /conversations

Query parameters. Newest first; pass the previous page’s nextCursor as cursor until it comes back null. /messages and /contacts page by creation, so a sync never skips a row; /conversations orders by latest activity, so a chat that gets a message while you page can move — sync with /messages instead.

FieldTypeWhat it is
limitnumber1–100, default 50.
cursoruuidThe nextCursor of the page before. Anything else is a 400.
conversationIduuid/messages only: one chat’s messages.
statusstring/messages only: queued, sent, delivered, read, failed or skipped.
searchstring/contacts only: part of a number, a name or a WhatsApp username.
channelstring/contacts only: "instagram" lists Instagram customers (their e164 is "ig:<id>", not a phone).

Returns 200 { "messages" | "contacts" | "conversations": [ … ], "nextCursor": "<uuid>" | null }. Every contact carries `userId` (their WhatsApp user id) and `username` (their WhatsApp username), null when WhatsApp has sent us neither. A WhatsApp customer whose number is not shared has "wa:<user id>" as e164. An Instagram customer also carries `instagram`: { "igsid", "username" } (null for everyone else).

PATCH /conversations/{id} · POST /conversations/{id}/notes

JSON body, agent keys.

FieldTypeWhat it is
statestringPATCH: open, pending or resolved.
prioritystringPATCH: low, normal, high or urgent.
isArchivedbooleanPATCH: archive or unarchive.
assignedAgentIduuid | nullPATCH: a team member’s user id, or null to unassign.
bodyrequiredstringNotes: the note, 1–5,000 characters. Never sent to the customer.

Returns PATCH → 200 with the conversation. Notes → 201 with the note.

Rate limits

The buckets these endpoints use. Burst is how many requests you can make back-to-back from a full bucket; sustained is how fast it refills.

BucketEndpointsBurstSustained
Reads/messages · /conversations · /contacts · /templates · /phone-numbers · GET /webhooks · Instagram reads · GET /payment-requests/{id}60060 / sec
Inbox writesPATCH /conversations/{id} · POST /conversations/{id}/notes (each its own bucket)12010 / sec

Every limit, the RateLimit-* headers and what to do on a 429: Rate limits.