> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get messages from multiple chats in bulk across the agency's creators (POST batch)
> Returns the most recent messages for chats grouped by creator, across the creators the authenticated user's agency manages, in a single request.
This collapses the outer per-creator fan-out: instead of one batch call per managed creator (`POST /creators/{creatorUserUuid}/chats/messages/batch`), agencies send one request grouping chat UUIDs under each creator. Each creator group takes the same `chatUuids`, `sinceMessageUuid` and `limit` fields as the per-creator batch, so per-key behaviour is identical — just add the creator dimension.
Per-creator and per-chat errors are reported inside the 200 response body, so a single forbidden/missing creator or chat never collapses the whole request. A creator the agency does not manage is returned as `{ "error": "forbidden" | "not_found" }` at the creator level.
Maximum 50 chat UUIDs in total across all creators, and 25 creators per request.
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.
Requires: Agency admin access
**Required scopes**
* `read:agency` — Read agency information, including the agency's team members.
* `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.
## OpenAPI
````yaml /openapi.json post /agencies/chats/messages/batch
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/agencies/chats/messages/batch:
post:
summary: >-
Get messages from multiple chats in bulk across the agency's creators
(POST batch)
description: >-
Returns the most recent messages for chats grouped by creator, across
the creators the authenticated user's agency manages, in a single
request.
This collapses the outer per-creator fan-out: instead of one batch call
per managed creator (`POST
/creators/{creatorUserUuid}/chats/messages/batch`), agencies send one
request grouping chat UUIDs under each creator. Each creator group takes
the same `chatUuids`, `sinceMessageUuid` and `limit` fields as the
per-creator batch, so per-key behaviour is identical — just add the
creator dimension.
Per-creator and per-chat errors are reported inside the 200 response
body, so a single forbidden/missing creator or chat never collapses the
whole request. A creator the agency does not manage is returned as `{
"error": "forbidden" | "not_found" }` at the creator level.
Maximum 50 chat UUIDs in total across all creators, and 25
creators per request.
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.
Requires: Agency admin access
operationId: batchAgencyMessages
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
creators:
type: array
items:
type: object
properties:
chatUuids:
type: array
items:
type: string
format: uuid
minItems: 1
maxItems: 50
description: >-
Array of chat UUIDs (counterpart user UUIDs) to fetch
messages for (1-50)
sinceMessageUuid:
type: string
format: uuid
description: >-
Optional cursor for incremental walks: returns only
messages strictly after this message's publish date in
each chat
limit:
type: integer
minimum: 1
maximum: 50
default: 20
description: >-
Maximum messages to return per chat (1-50, default:
20)
creatorUserUuid:
type: string
format: uuid
description: UUID of a creator the agency manages
required:
- chatUuids
- creatorUserUuid
minItems: 1
maxItems: 25
description: Per-creator groups of chat UUIDs (1-25 creators)
required:
- creators
responses:
'200':
description: >-
Per-creator, per-chat messages or error. Always 200 when the request
itself is valid, even if every key fails.
content:
application/json:
schema:
type: object
properties:
byCreator:
type: object
additionalProperties:
anyOf:
- type: object
properties:
byChat:
type: object
additionalProperties:
anyOf:
- type: object
properties:
messages:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
text:
type:
- string
- 'null'
sentAt:
type:
- string
- 'null'
format: date
sender:
type: object
properties:
uuid:
type: string
format: uuid
handle:
type: string
required:
- uuid
- handle
recipient:
type: object
properties:
uuid:
type: string
format: uuid
handle:
type: string
hasMedia:
type:
- boolean
- 'null'
mediaType:
type:
- string
- 'null'
enum:
- image
- video
- audio
- document
mediaUuids:
type: array
items:
type: string
format: uuid
description: >-
Ordered list of media UUIDs attached to
this message (display order)
mediaPreviewUuid:
type:
- string
- 'null'
format: uuid
description: >-
UUID of the media item shown for free as
a preview of this pay-to-view message,
or null when no free preview was
configured. Mirrors the
`mediaPreviewUuid` set when sending the
message.
type:
type: string
enum:
- AUTOMATED_CANCELED
- AUTOMATED_NEW_FOLLOWER
- AUTOMATED_NEW_PURCHASE
- AUTOMATED_NEW_SUBSCRIBER
- AUTOMATED_RE_SUBSCRIBED
- AUTOMATED_RENEWED
- AUTOMATED_CHAT_MESSAGE_REPLY
- AUTOMATED_FIRST_MESSAGE_REPLY
- CHAT_TEXT_GENERATION
- CHAT_TEXT_REPLY
- CHAT_TEXT_REWRITE
- SINGLE_RECIPIENT
- TIP
- VOICE_CALL
- BROADCAST
- GHOST_PROMOTION
pricing:
type:
- object
- 'null'
properties:
USD:
type: object
properties:
price:
type: number
description: Price in cents
required:
- price
required:
- USD
description: >-
Pricing information for pay-to-view
messages
purchasedAt:
type:
- string
- 'null'
format: date
description: >-
Timestamp when this message was
purchased, or null if not purchased
tipSource:
type:
- string
- 'null'
enum:
- chat
- post
- media_link
description: >-
For TIP messages, where the tip
originated: 'chat' (direct in-chat tip),
'post' (tipped a feed post) or
'media_link' (tipped via a shared media
link). Null for non-tip messages.
sentByUserId:
type:
- string
- 'null'
format: uuid
description: >-
UUID of the team member who sent the
message on behalf of the creator, or
null if sent directly by the creator
isRead:
type: boolean
description: >-
Whether the message has been read by the
recipient
required:
- uuid
- text
- sentAt
- sender
- recipient
- hasMedia
- mediaType
- mediaUuids
- mediaPreviewUuid
- type
- pricing
- purchasedAt
- tipSource
- sentByUserId
- isRead
hasMore:
type: boolean
description: >-
Whether more messages exist beyond the
returned set (older than
`oldestMessageUuid` for the default
newest-first read, or in the queried
range for incremental walks)
oldestMessageUuid:
type:
- string
- 'null'
format: uuid
description: >-
UUID of the oldest message in the
returned batch, or null if no messages
were returned
required:
- messages
- hasMore
- oldestMessageUuid
- type: object
properties:
error:
type: string
enum:
- forbidden
- not_found
- internal
required:
- error
description: >-
Map of input chat UUID to messages or a per-key
error
required:
- byChat
- type: object
properties:
error:
type: string
enum:
- forbidden
- not_found
- internal
required:
- error
description: >-
Map of input creator UUID to its per-chat messages, or a
creator-level error (forbidden/not_found).
required:
- byCreator
example:
byCreator:
c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8:
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: []
mediaPreviewUuid: null
pricing: null
purchasedAt: null
sentByUserId: null
isRead: true
hasMore: true
oldestMessageUuid: a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6
c3d4e5f6-7890-1234-5678-9abcdef01234:
error: not_found
22222222-2222-4222-8222-222222222222:
error: forbidden
'400':
description: >-
Bad Request - API version not supported OR validation failed (dates,
sources, cursor, pagination)
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- read:agency
- read:chat
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
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.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````