Skip to content

REST API v1 · Resource

Reading

Who is calling, your numbers, and the messages, conversations and contacts in your workspace.

API reference · Reading

Last updated

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).

Reading

6
  • GET/meWho is calling: your workspace, and the key’s label, role and expiry (never the key itself). The connection test for Zapier, Make and PabblyScope any key · viewer role or higher
  • GET/messagesList messages, cursor-paginated. Filter by conversationId and statusScope messages:read · viewer role or higher
  • GET/messages/{id}Get one message and its delivery status — by our id or by wamidScope messages:read · viewer role or higher
  • GET/conversationsList WhatsApp conversations with contact info and window expiryScope conversations:read · viewer role or higher
  • GET/contactsList contacts, cursor-paginated. Filter with ?search= (any part of a name or number), ?phone= (one exact number); ?channel=instagram for Instagram customersScope contacts:read · viewer role or higher
  • GET/phone-numbersYour WhatsApp numbers — the ids phoneNumberId refers to, the default first, each with the account behind it (wabaConnectionId, wabaId, accountStatus)Scope any key · 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).

Examples

cURL
# Check what happened to a message (by our id or by the wamid webhooks carry)
curl https://fliok.com/api/v1/messages/wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS \
  -H "Authorization: Bearer wa_YOUR_API_KEY"

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, LinkedIn, ads and catalog reads · GET /payment-requests/{id}60060 / sec

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