> ## 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 list of chats
> Returns a paginated list of chat conversations with optional filtering, searching, and sorting.
**Available Filters** (via `filter` parameter):
- `unread` - Only unread chats
- `online` - Only online users
- `subscribed_to` - Users you're subscribed to
- `not_muted` - Exclude muted chats
- `subscribers` - Only subscribers (creator-only)
- `followers` - Only followers (creator-only)
- `recent_subscribers` - Recently subscribed (creator-only)
- `not_answered` - Unanswered chats (creator-only)
- `spent_more_than_50` - High spenders (creator-only)
- `on_free_trial` - Free trial users (creator-only)
- `has_tipped` - Users who have tipped (creator-only)
- `spenders` - All spenders (creator-only)
- `exclude_creators` - Exclude creator accounts (creator-only)
**Sort Options** (via `sortBy` parameter):
- `most_recent_messages` (default) - Sort by most recent message
- `online_now` - Prioritize online users
- `most_unanswered_chats` - Sort by unanswered count
**Sort Direction** (via `sortDirection` parameter):
- `desc` (default) - Highest-ranked chats first (most recent / most online / most unanswered)
- `asc` - Reverses the order (least recent / least online / fewest unanswered)
Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.
**Required scope**
* `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.
## OpenAPI
````yaml /openapi.json get /chats
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/chats:
get:
summary: Get list of chats
description: >-
Returns a paginated list of chat conversations with optional filtering,
searching, and sorting.
**Available Filters** (via `filter` parameter):
- `unread` - Only unread chats
- `online` - Only online users
- `subscribed_to` - Users you're subscribed to
- `not_muted` - Exclude muted chats
- `subscribers` - Only subscribers (creator-only)
- `followers` - Only followers (creator-only)
- `recent_subscribers` - Recently subscribed (creator-only)
- `not_answered` - Unanswered chats (creator-only)
- `spent_more_than_50` - High spenders (creator-only)
- `on_free_trial` - Free trial users (creator-only)
- `has_tipped` - Users who have tipped (creator-only)
- `spenders` - All spenders (creator-only)
- `exclude_creators` - Exclude creator accounts (creator-only)
**Sort Options** (via `sortBy` parameter):
- `most_recent_messages` (default) - Sort by most recent message
- `online_now` - Prioritize online users
- `most_unanswered_chats` - Sort by unanswered count
**Sort Direction** (via `sortDirection` parameter):
- `desc` (default) - Highest-ranked chats first (most recent / most
online / most unanswered)
- `asc` - Reverses the order (least recent / least online / fewest
unanswered)
Some filters are only available to creators. Using creator-only
filters as a non-creator will return a 403 error.
operationId: listChats
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: number
minimum: 1
default: 1
description: Page number to retrieve (starts from 1)
required: false
description: Page number to retrieve (starts from 1)
name: page
in: query
- schema:
type: number
minimum: 1
maximum: 50
default: 15
description: 'Number of items to return per page (1-50, default: 15)'
required: false
description: 'Number of items to return per page (1-50, default: 15)'
name: size
in: query
- schema:
type: string
format: uuid
description: Filter chats by custom list UUID
required: false
description: Filter chats by custom list UUID
name: customListId
in: query
- schema:
type: array
items:
type: string
format: uuid
description: >-
Filter chats to these counterpart (fan) user UUIDs (repeat the
param for multiple)
required: false
description: >-
Filter chats to these counterpart (fan) user UUIDs (repeat the param
for multiple)
name: userUuids
in: query
- schema:
type: array
items:
type: string
enum:
- subscribers
- auto_renewing
- non_renewing
- followers
- free_trial_subscribers
- expired_subscribers
- spent_more_than_50
- muted
- creators
description: Filter chats by smart list type(s)
required: false
description: Filter chats by smart list type(s)
name: smartListIds
in: query
- schema:
type: array
items:
type: string
enum:
- unread
- subscribers
- followers
- online
- recent_subscribers
- not_answered
- spent_more_than_50
- on_free_trial
- has_tipped
- spenders
- exclude_creators
- subscribed_to
- not_muted
- archived
description: Filter types to apply (can specify multiple via repeated params)
required: false
description: Filter types to apply (can specify multiple via repeated params)
name: filter
in: query
- schema:
type: string
maxLength: 100
description: Search term to filter chats by user name/handle
required: false
description: Search term to filter chats by user name/handle
name: search
in: query
- schema:
type: string
enum:
- most_recent_messages
- online_now
- most_unanswered_chats
description: 'Sort order for chat list (default: most_recent_messages)'
required: false
description: 'Sort order for chat list (default: most_recent_messages)'
name: sortBy
in: query
- schema:
type: string
enum:
- asc
- desc
description: 'Sort direction for chat list (default: desc)'
required: false
description: 'Sort direction for chat list (default: desc)'
name: sortDirection
in: query
responses:
'200':
description: List of chats
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
createdAt:
type:
- string
- 'null'
format: date
lastMessageAt:
type:
- string
- 'null'
format: date
description: Date of the last message in this chat
isRead:
type: boolean
description: >-
Whether the chat is marked as read (true) or unread
(false)
isMuted:
type: boolean
unreadMessagesCount:
type: number
user:
type: object
properties:
uuid:
type: string
format: uuid
handle:
type: string
displayName:
type: string
nickname:
type:
- string
- 'null'
isTopSpender:
type: boolean
avatarUrl:
type:
- string
- 'null'
registeredAt:
type: string
format: date-time
required:
- uuid
- handle
- displayName
- nickname
- isTopSpender
- avatarUrl
- registeredAt
lastMessage:
type:
- object
- 'null'
properties:
text:
type:
- string
- 'null'
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
uuid:
type: string
sentAt:
type:
- string
- 'null'
format: date
hasMedia:
type:
- boolean
- 'null'
mediaType:
type:
- string
- 'null'
enum:
- image
- video
- audio
- document
senderUuid:
type: string
format: uuid
senderRole:
type: string
enum:
- FAN
- CREATOR
- AGENCY
- SYSTEM
description: >-
Who sent the last message: CREATOR (the creator,
sent directly), AGENCY (a team member sent it on
the creator's behalf), FAN (the counterpart fan)
or SYSTEM (an automated/platform message such as
a subscription automation or KYC prompt).
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
status:
type:
- string
- 'null'
enum:
- Sent
- Delivered
- Read
description: >-
Delivery status of the last message from the
sender's perspective: Sent (still in flight),
Delivered (sent but not yet read by the
recipient) or Read. Null when the last message
was received by the authenticated user
(inbound).
required:
- text
- type
- uuid
- sentAt
- hasMedia
- mediaType
- senderUuid
- senderRole
- sentByUserId
isCreator:
type: boolean
description: >-
Whether the chat counterpart is also a creator on
the platform
online:
type: boolean
description: >-
Whether the counterpart is currently online.
Provided inline to avoid a separate /chats/statuses
request.
lastSeenAt:
type:
- string
- 'null'
format: date
description: >-
When the counterpart was last seen online, or null
if unknown/hidden
customLists:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
description: Custom list UUID
name:
type: string
description: Custom list name
required:
- uuid
- name
description: >-
Custom lists owned by the authenticated user that
the counterpart belongs to
required:
- createdAt
- lastMessageAt
- isRead
- isMuted
- unreadMessagesCount
- user
- lastMessage
description: Array of chat conversations
pagination:
type: object
properties:
page:
type: number
description: Current page number
size:
type: number
description: Number of records returned in this response
hasMore:
type: boolean
description: >-
Whether there are more items available on subsequent
pages
required:
- page
- size
- hasMore
description: Pagination information
required:
- data
- pagination
example:
data:
- createdAt: '2024-01-15T00:00:00.000Z'
lastMessageAt: '2024-01-15T00:00:00.000Z'
isRead: false
isMuted: false
unreadMessagesCount: 3
user:
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'
isCreator: false
online: true
lastSeenAt: '2024-01-15T00:00:00.000Z'
customLists:
- uuid: c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8
name: VIPs
lastMessage:
uuid: a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6
text: Hey there! How are you doing?
type: SINGLE_RECIPIENT
sentAt: '2024-01-15T00:00:00.000Z'
hasMedia: true
mediaType: image
senderUuid: c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8
senderRole: CREATOR
sentByUserId: null
status: Read
- createdAt: '2024-01-14T00:00:00.000Z'
lastMessageAt: null
isRead: true
isMuted: true
unreadMessagesCount: 0
user:
uuid: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
handle: mike-smith
nickname: null
displayName: Mike Smithly
isTopSpender: false
avatarUrl: https://media.fanvue.com/avatars/example-avatar.jpg
registeredAt: '2024-01-10T12:00:00.000Z'
lastMessage: null
- createdAt: '2024-01-15T00:00:00.000Z'
lastMessageAt: '2024-01-15T00:00:00.000Z'
isRead: true
isMuted: false
unreadMessagesCount: 0
user:
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'
lastMessage:
uuid: c3d4e5f6-7890-1234-5678-9abcdef01234
text: Check out my new post!
type: BROADCAST
sentAt: '2024-01-15T00:00:00.000Z'
hasMedia: true
mediaType: image
senderUuid: c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8
senderRole: CREATOR
sentByUserId: null
status: Delivered
pagination:
page: 1
size: 2
hasMore: false
'400':
description: Bad Request - API version not supported OR validation failed
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: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.
````