Get messages from multiple chats in bulk

Changed on

Returns the most recent messages for up to 50 chats in a single request, keyed by the input chat UUID (the counterpart user UUID).

This is the bulk counterpart to GET /chats/{userUuid}/messages. It collapses N per-chat round trips into one POST and is intended for initial-sync flows and incremental refreshes.

Per-key errors are reported inside the 200 response body so a single unreachable chat never collapses the whole request — consumers keep the rest and only retry the failing keys.

Modes:

  • Default: returns the latest limit messages per chat, newest first. hasMore indicates older messages exist.
  • Incremental (sinceMessageUuid): returns messages strictly newer than the cursor message, newest first. The cursor is the message itself, not its timestamp, so a message sharing the cursor's publish instant is still returned.

Out of scope: Backwards history pagination (a before cursor). Use oldestMessageUuid from the response as the anchor when that ships.

<Note>Maximum 50 chat UUIDs per request. Failed keys are reported as { "error": "not_found" } — this covers both chats that don't exist and chats the caller isn't part of.</Note>

<Note>Read-only: fetching messages in bulk does not mutate read state — messages are not marked read and isRead reflects each message's state at read time.</Note>

<Note>Direct messages only. Mass (broadcast) messages are excluded from this endpoint. The per-chat listing endpoints include them interleaved with the 1:1 thread, so the two surfaces legitimately return different messages for the same chat — a message present in a chat listing can be absent here without anything being lost. Creators can list the broadcasts they sent via GET /chats/mass-messages; that endpoint is creator-only, so fans have no separate listing of received broadcasts and should read them from the per-chat listing.</Note>

<Note>Rate-limit cost. Each request consumes one rate-limit point per 10 chat UUIDs, rounded up: 1-10 chats cost 1 point, 50 chats cost 5.</Note>

post/chats/messages/batch

Request

  • Base URL
    https://api.fanvue.com
  • URL
    https://api.fanvue.com/chats/messages/batch
  • Auth
    OAuth 2
    Authorization code: https://auth.fanvue.com/oauth2/auth
    Token URL: https://auth.fanvue.com/oauth2/token scopes: read:chat

Headers

X-Fanvue-API-Versionstring required
Example:2025-06-26

API version to use for the request

Request body

chatUuidsstring[] required

Array of chat UUIDs (counterpart user UUIDs) to fetch messages for (1-50)

sinceMessageUuidstring uuid

Optional cursor for incremental walks: returns only messages strictly newer than this message in each chat. Anchored on the message, not its timestamp, so a message published in the same instant is not skipped

limitinteger

Maximum messages to return per chat (1-50, default: 20)

Response

Per-chat messages or error for each requested chat. Always 200 when the request itself is valid, even if every key fails.

byChatobject required

Map of input chat UUID to messages or a per-key error

Changes

    • info

      added the required property ///// to the response with the status