Get messages from multiple chats in bulk

curl --request POST \
  --url https://api.fanvue.com/chats/messages/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>' \
  --data '
{
  "chatUuids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}
'

{
  "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.

Scope required: read:chat

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.

POST

chats

messages

batch

Get messages from multiple chats in bulk

curl --request POST \
  --url https://api.fanvue.com/chats/messages/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>' \
  --data '
{
  "chatUuids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}
'

{
  "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"
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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

⌘I