> ## 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-v1.json post /v1/agencies/chats/messages/batch
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/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.
gif:
type:
- object
- 'null'
properties:
id:
type: string
description: >-
The GIF provider's durable identifier
for this GIF. Stable across renditions;
use it to de-duplicate or re-resolve the
GIF.
format:
type: string
enum:
- GIF
- WEBP
- MP4
- WEBM
description: >-
Encoding of the asset at `url`. Only
`GIF` and `WEBP` are produced today, and
both render in a plain ![]()
tag.
title:
type:
- string
- 'null'
description: >-
Human-readable GIF title, suitable as
alt text.
url:
type:
- string
- 'null'
description: >-
Hotlink URL of the GIF, served from the
provider's CDN — Fanvue does not host or
proxy the asset. Null when the URL is
temporarily withheld; the message is
still a GIF message, so render a
placeholder at `width`/`height` rather
than treating it as empty.
width:
type: integer
exclusiveMinimum: 0
description: >-
Intrinsic width of the asset at `url`,
in pixels
height:
type: integer
exclusiveMinimum: 0
description: >-
Intrinsic height of the asset at `url`,
in pixels
required:
- id
- format
- title
- url
- width
- height
description: >-
The third-party GIF attached to this
message, or null for an ordinary
message. A GIF message carries no media
and no price, but `text` may be set — a
GIF can be sent with a caption.
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
appUuid:
type:
- string
- 'null'
format: uuid
description: >-
UUID of the third-party app that created
this message through the public API.
Null when the message was sent from the
Fanvue dashboard, and for every message
sent before app attribution was
recorded.
isRead:
type: boolean
description: >-
Whether the message has been read by the
recipient
required:
- uuid
- text
- sentAt
- sender
- recipient
- hasMedia
- mediaType
- mediaUuids
- mediaPreviewUuid
- gif
- type
- pricing
- purchasedAt
- tipSource
- sentByUserId
- appUuid
- 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
gif: null
pricing: null
purchasedAt: null
sentByUserId: null
appUuid: f6a7b8c9-0123-4567-89ab-cdef01234567
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.
````