Get messages

Retrieve conversation history for an account-owned agent channel of type api. The history belongs to the conversation thread identified by the agent channel and your external contact or session ID.

Back to the API overview

GET https://api.openfi.tech/v1/messages?agentChannelId=AGENT_CHANNEL_ID&contactChannelExternalId=CUSTOMER_USER_ID
x-api-key: YOUR_API_KEY

URL encode all query parameter values.

Query parameters

Field	Type	Required	Description
`agentChannelId`	UUID	Yes	The account-owned API agent channel handling the conversation.
`contactChannelExternalId`	string	Yes	Your non-empty, stable identifier for the end user or chat session.
`cursor`	UUID	No	The nextCursor returned by the previous, newer page.

Example request

Load the API key into ZEUS_API_KEY from your secret manager or a secure shell prompt. curl --data-urlencode safely encodes the thread identifiers.

curl --get 'https://api.openfi.tech/v1/messages' \
  --header "x-api-key: ${ZEUS_API_KEY}" \
  --data-urlencode 'agentChannelId=YOUR_API_AGENT_CHANNEL_ID' \
  --data-urlencode 'contactChannelExternalId=customer-user-123'

Response

A successful request returns 200 OK:

{
  "messages": [
    {
      "id": "6d66d1a0-f2d2-4bb6-942d-c64b9c981a79",
      "agentChannelId": "8dc72cb9-eaf2-4b6f-af0d-e68ee6add246",
      "contactChannelExternalId": "customer-user-123",
      "content": "Hi, how can I help?",
      "type": "Outgoing",
      "createdAt": "2026-08-03T10:00:00.000Z",
      "updatedAt": "2026-08-03T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}

type is Incoming or Outgoing. Each message carries the public channel pair so it remains self-identifying. Internal channel IDs, provider payloads, and model execution data are not returned.

If the API agent channel exists but the thread has no persisted messages, the endpoint returns an empty messages array and nextCursor: null.

Pagination

The page size is fixed at 100 messages. Without a cursor, the endpoint returns the latest page. Every page is ordered from oldest to newest using createdAt and then id for deterministic ordering.

When older messages exist, nextCursor is the ID of the oldest message in the returned page. Supply it as cursor to load the next page of messages strictly older than that message. The cursor message is not repeated. nextCursor is null when no older messages remain.

curl --get 'https://api.openfi.tech/v1/messages' \
  --header "x-api-key: ${ZEUS_API_KEY}" \
  --data-urlencode 'agentChannelId=YOUR_API_AGENT_CHANNEL_ID' \
  --data-urlencode 'contactChannelExternalId=customer-user-123' \
  --data-urlencode 'cursor=6d66d1a0-f2d2-4bb6-942d-c64b9c981a79'

A cursor must identify a message in the requested thread. An unknown cursor or one from another thread returns 400 Bad Request.

Reconciliation

History spans all intents associated with the channel pair. Use webhooks for normal real-time updates and persist those updates on your server. Use this endpoint to recover missing or stale local state and to load older history, rather than polling it after every webhook.

Webhook snapshots contain at most the latest 100 messages for the affected intent. This endpoint paginates the complete thread history across intents. Merge messages by id and apply the newest updatedAt value when reconciling stored state.

Errors

Status	Meaning
`400 Bad Request`	A required query parameter is missing or invalid, or the cursor does not belong to the requested thread.
`401 Unauthorized`	The x-api-key header is missing or invalid.
`404 Not Found`	The agent channel is missing, belongs to another account, or is not an API channel.
`429 Too Many Requests`	The account exceeded 10,000 history requests in 24 hours. Follow Retry-After before retrying.
`500 Internal Server Error`	An unexpected error occurred. Retry with backoff.

If a saved cursor becomes invalid, restart without a cursor to load the latest page and reconcile it with your stored messages.