> ## 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 a chat
> Returns a date-based list of text messages between the authenticated user and the specified user. Messages are ordered by date (newest first).
**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to date-based pagination with separate filters for sent and received messages.
**Pagination Flow:**
- First request: No date filters needed, returns first 20 messages (or specified limit)
- Subsequent requests: Use the date filters from the previous response
- End of results: date filters will be `null`
**Partial Filters Supported:**
You can provide:
- Both `sentBefore` and `receivedBefore` for standard pagination
- Only `sentBefore` to filter messages sent by the user
- Only `receivedBefore` to filter messages received from the user
- Neither filter for the first request
**Date Filter Structure:**
The response contains two date filters:
```json
{
// Date filter for messages sent by user (use for next request)
"sentBefore": "2024-01-10T12:00:00Z",
// Date filter for messages received by user (use for next request)
"receivedBefore": "2024-01-10T11:00:00Z"
}
```
Both filters can be `null` if messages only flow in one direction.
**Polling for real-time updates? Use a webhook instead.**
If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.message.received`, `creator.message.sent`, `creator.message.deleted`, `creator.message.reaction` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/messages).
**Required scope**
* `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.
## OpenAPI
````yaml /openapi-v1.json get /v1/chats/{userUuid}/messages
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/chats/{userUuid}/messages:
get:
summary: Get messages from a chat
description: >-
Returns a date-based list of text messages between the authenticated
user and the specified user. Messages are ordered by date (newest
first).
**v1-experimental Breaking Change**: Switched from offset-based
pagination (`page`/`size`) to date-based pagination with separate
filters for sent and received messages.
**Pagination Flow:**
- First request: No date filters needed, returns first 20 messages (or
specified limit)
- Subsequent requests: Use the date filters from the previous response
- End of results: date filters will be `null`
**Partial Filters Supported:**
You can provide:
- Both `sentBefore` and `receivedBefore` for standard pagination
- Only `sentBefore` to filter messages sent by the user
- Only `receivedBefore` to filter messages received from the user
- Neither filter for the first request
**Date Filter Structure:**
The response contains two date filters:
```json
{
// Date filter for messages sent by user (use for next request)
"sentBefore": "2024-01-10T12:00:00Z",
// Date filter for messages received by user (use for next request)
"receivedBefore": "2024-01-10T11:00:00Z"
}
```
Both filters can be `null` if messages only flow in one direction.
**Polling for real-time updates? Use a webhook instead.**
If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.message.received`, `creator.message.sent`, `creator.message.deleted`, `creator.message.reaction` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/messages).
operationId: listMessages_v1_experimental
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: uuid
required: true
name: userUuid
in: path
- schema:
type:
- string
- 'null'
format: date
description: Fetch messages sent before this date
required: false
description: Fetch messages sent before this date
name: sentBefore
in: query
- schema:
type:
- string
- 'null'
format: date
description: Fetch messages received before this date
required: false
description: Fetch messages received before this date
name: receivedBefore
in: query
- schema:
type: number
minimum: 1
maximum: 50
default: 20
description: 'Number of messages to return (1-50, default: 20)'
required: false
description: 'Number of messages to return (1-50, default: 20)'
name: limit
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: Whether to mark the chat as read after retrieving messages
required: false
description: Whether to mark the chat as read after retrieving messages
name: markAsRead
in: query
responses:
'200':
description: Date-based list of messages
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
text:
type:
- string
- 'null'
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. `text` may be set
alongside it — a GIF can be sent with a caption.
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
required:
- uuid
- handle
type:
type: string
enum:
- AUTOMATED_CANCELED
- AUTOMATED_NEW_FOLLOWER
- AUTOMATED_NEW_PURCHASE
- AUTOMATED_NEW_SUBSCRIBER
- AUTOMATED_RE_SUBSCRIBED
- AUTOMATED_RENEWED
- AUTOMATED_FIRST_MESSAGE_REPLY
- AUTOMATED_CHAT_MESSAGE_REPLY
- BROADCAST
- CHAT_TEXT_GENERATION
- CHAT_TEXT_REWRITE
- CHAT_TEXT_REPLY
- GHOST_PROMOTION
- MARKETING_KYC
- TIP
- LOCKED_MESSAGE_UNLOCKED
- VOICE_CALL
- SINGLE_RECIPIENT
status:
type: string
enum:
- SENT
- UNSENT
- MODERATED
isRead:
type: boolean
isSubscribed:
type: boolean
isFollowing:
type: boolean
followForFreeEnabled:
type: boolean
repliedMessage:
type:
- object
- 'null'
properties:
parent_message_id:
type: number
child_message_id:
type: number
parent_message:
type: object
properties:
uuid:
type: string
format: uuid
id:
type: number
text:
type:
- string
- 'null'
created_at:
type:
- string
- 'null'
format: date
published_at:
type:
- string
- 'null'
format: date
owner_id:
type: number
recipient_id:
type:
- number
- 'null'
price:
type:
- number
- 'null'
publish_at:
type:
- string
- 'null'
format: date
status:
type: string
enum:
- SENT
- UNSENT
- MODERATED
type:
type: string
enum:
- AUTOMATED_CANCELED
- AUTOMATED_NEW_FOLLOWER
- AUTOMATED_NEW_PURCHASE
- AUTOMATED_NEW_SUBSCRIBER
- AUTOMATED_RE_SUBSCRIBED
- AUTOMATED_RENEWED
- AUTOMATED_FIRST_MESSAGE_REPLY
- AUTOMATED_CHAT_MESSAGE_REPLY
- BROADCAST
- CHAT_TEXT_GENERATION
- CHAT_TEXT_REWRITE
- CHAT_TEXT_REPLY
- GHOST_PROMOTION
- MARKETING_KYC
- TIP
- LOCKED_MESSAGE_UNLOCKED
- VOICE_CALL
- SINGLE_RECIPIENT
sender:
type: object
properties:
id:
type: number
uuid:
type: string
format: uuid
is_creator:
type: boolean
handle:
type: string
required:
- id
- uuid
- is_creator
- handle
required:
- uuid
- id
- text
- created_at
- published_at
- owner_id
- recipient_id
- price
- publish_at
- status
- type
- sender
required:
- parent_message_id
- child_message_id
- parent_message
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.
required:
- uuid
- text
- gif
- sentAt
- sender
- recipient
- type
- status
- isRead
- isSubscribed
- isFollowing
- followForFreeEnabled
- repliedMessage
- sentByUserId
- appUuid
dateFilter:
type:
- object
- 'null'
properties:
sentBefore:
type:
- string
- 'null'
format: date
receivedBefore:
type:
- string
- 'null'
format: date
required:
- sentBefore
- receivedBefore
description: Next date filters, null if no more results
required:
- data
- dateFilter
example:
data:
- uuid: 550e8400-e29b-41d4-a716-446655440000
text: Hey there! How are you doing?
gif: null
sentAt: '2024-01-10T12:00:00.000Z'
sender:
uuid: 550e8400-e29b-41d4-a716-446655440001
handle: sarah
recipient:
uuid: 550e8400-e29b-41d4-a716-446655440002
handle: johnny
type: TEXT
status: SENT
isRead: true
isSubscribed: true
isFollowing: false
followForFreeEnabled: false
repliedMessage: null
sentByUserId: null
appUuid: f6a7b8c9-0123-4567-89ab-cdef01234567
- uuid: 660e8400-e29b-41d4-a716-446655440001
text: I'm doing great! Thanks for asking.
gif: null
sentAt: '2024-01-10T11:59:00.000Z'
sender:
uuid: 550e8400-e29b-41d4-a716-446655440002
handle: johnny
recipient:
uuid: 550e8400-e29b-41d4-a716-446655440001
handle: sarah
type: TEXT
status: SENT
isRead: true
isSubscribed: true
isFollowing: false
followForFreeEnabled: false
repliedMessage: null
sentByUserId: null
appUuid: null
- uuid: 770e8400-e29b-41d4-a716-446655440002
text: null
gif:
id: excited-happy-dance-xY7bQ
format: WEBP
title: excited happy dance
url: https://cdn.klipy.com/excited-happy-dance-xY7bQ/md.webp
width: 480
height: 360
sentAt: '2024-01-10T11:58:00.000Z'
sender:
uuid: 550e8400-e29b-41d4-a716-446655440002
handle: johnny
recipient:
uuid: 550e8400-e29b-41d4-a716-446655440001
handle: sarah
type: TEXT
status: SENT
isRead: true
isSubscribed: true
isFollowing: false
followForFreeEnabled: false
repliedMessage: null
sentByUserId: null
appUuid: null
dateFilter:
sentBefore: '2024-01-10T12:00:00.000Z'
receivedBefore: '2024-01-10T11:59:00.000Z'
'400':
description: >-
Bad Request - API version not supported OR validation failed OR
invalid UUID
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/InvalidUuidError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
description: No conversation found with the given user
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
'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
InvalidUuidError:
type: object
properties:
message:
type: string
required:
- message
description: Invalid UUID format provided
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.
````