Skip to navigation
API ReferenceConversations

Retrieve a conversation

View as Markdown

Returns one conversation of the workspace, active or closed, with the same joined fields as GET /api/conversations plus messages: the most recent limit messages of the thread (50 by default), in chronological order (created_at ascending, oldest of the page first).

Paging older messages. meta.messages describes the page. When hasMore is true, nextBefore is the id of the oldest message returned: send it as before to get the limit messages immediately older than it, and prepend that page. nextBefore is null on the first page of the thread. Messages sharing a timestamp are ordered by id, so none is skipped or repeated between pages. A before that is not a message of this conversation returns an empty messages array with hasMore: false. The conversation fields are the same on every page.

Message content is cleaned for display: the delimiter tags wrapped around customer text before it reaches the model (e.g. <user_message>) are stripped. Each message also carries attachment, the name, type and size of a file the contact sent, or null. File bytes are never stored.

Consistency. The newest page at the default limit of 50 is cached for up to 30 seconds; pages requested with before or another limit are read fresh. An operator reply through POST /api/conversations/{conversationId}/messages clears the cache immediately. Resolving a human-help request does not, so needs_human_resolved_at can lag for up to 30 seconds.

Access

  • Required scope: read (or write).
  • Rate limit: General API — 120 requests/min per workspace (Starter), 200 (Growth), 300 (Business), 600 (Enterprise). See Rate limits.
  • Plan: Available on every plan.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

ScopeGET / HEADPOST / PUT / PATCH / DELETEAdmin-only routes
readYesNoNo
writeYesYesNo
fullYesYesYes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Path parameters

conversationIdstringRequiredformat: "uuid"
Id of the conversation. A value that is not a UUID returns 400.

Query parameters

limitintegerOptional1-200Defaults to 50
Messages per page, 1 to 200. Any other value returns 400.
beforestringOptionalformat: "uuid"

Id of a message in this conversation (meta.messages.nextBefore from the previous page). Returns the messages older than it. A value that is not a UUID returns 400.

Response

The conversation and one page of its messages, newest page first.
dataobject

A text conversation (WhatsApp, email, webchat, Instagram or Messenger) as returned by GET /api/conversations and GET /api/conversations/{conversationId}. Fields are the conversations row (snake_case) plus contact, agent and last-message columns joined in, and a derived qualification. Analysis and telemetry columns are null until the conversation has been analysed. null means not measured, never zero or neutral.

metaobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error