Get messages from multiple chats in bulk

curl --request POST \
  --url https://api.example.com/chats/messages/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>' \
  --data '
{
  "chatUuids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

{
  "byChat": {
    "b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7": {
      "messages": [
        {
          "uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
          "text": "Hey there! How are you doing?",
          "sentAt": "2024-01-15T00:00:00.000Z",
          "sender": {
            "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "handle": "sarah-jones",
            "nickname": "SarahK",
            "displayName": "Sarah Jones",
            "isTopSpender": true,
            "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
            "registeredAt": "2024-01-10T12:00:00.000Z"
          },
          "recipient": {
            "uuid": "3bbe6394-2830-4646-a8ba-4a0a05426947",
            "handle": "johnny-doey",
            "nickname": "JohnnyD",
            "displayName": "Johnny Doey",
            "isTopSpender": true,
            "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
            "registeredAt": "2024-01-10T12:00:00.000Z"
          },
          "type": "SINGLE_RECIPIENT",
          "hasMedia": false,
          "mediaType": null,
          "mediaUuids": [],
          "pricing": null,
          "purchasedAt": null,
          "sentByUserId": null,
          "isRead": true
        }
      ],
      "hasMore": true,
      "oldestMessageUuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
    },
    "c3d4e5f6-7890-1234-5678-9abcdef01234": {
      "error": "not_found"
    }
  }
}

Chats

Get messages from multiple chats in bulk

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 published after the cursor message’s publish date, newest first.

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

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.

POST

chats

messages

batch

Get messages from multiple chats in bulk

curl --request POST \
  --url https://api.example.com/chats/messages/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>' \
  --data '
{
  "chatUuids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

{
  "byChat": {
    "b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7": {
      "messages": [
        {
          "uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
          "text": "Hey there! How are you doing?",
          "sentAt": "2024-01-15T00:00:00.000Z",
          "sender": {
            "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "handle": "sarah-jones",
            "nickname": "SarahK",
            "displayName": "Sarah Jones",
            "isTopSpender": true,
            "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
            "registeredAt": "2024-01-10T12:00:00.000Z"
          },
          "recipient": {
            "uuid": "3bbe6394-2830-4646-a8ba-4a0a05426947",
            "handle": "johnny-doey",
            "nickname": "JohnnyD",
            "displayName": "Johnny Doey",
            "isTopSpender": true,
            "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
            "registeredAt": "2024-01-10T12:00:00.000Z"
          },
          "type": "SINGLE_RECIPIENT",
          "hasMedia": false,
          "mediaType": null,
          "mediaUuids": [],
          "pricing": null,
          "purchasedAt": null,
          "sentByUserId": null,
          "isRead": true
        }
      ],
      "hasMore": true,
      "oldestMessageUuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
    },
    "c3d4e5f6-7890-1234-5678-9abcdef01234": {
      "error": "not_found"
    }
  }
}

Required scope

read:chat — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.

Authorizations

Authorization

string

header

required

OAuth 2.0 access token, presented as a JWT bearer token in the Authorization header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call.

Headers

X-Fanvue-API-Version

string

default:2025-06-26

required

API version to use for the request

Example:

"2025-06-26"

Body

application/json

chatUuids

string<uuid>[]

required

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

Required array length: 1 - 50 elements

sinceMessageUuid

string<uuid>

Optional cursor for incremental walks: returns only messages strictly after this message's publish date in each chat

limit

integer

default:20

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

Required range: 1 <= x <= 50

Response

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

byChat

object

required

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

Show child attributes

Send a message Delete a message