Get list of chats | Fanvue API Documentation

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

Scope required: read:chat

Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.

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 <Info>Scope required: `read:chat`</Info> <Warning>Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.</Warning>

Authentication

AuthorizationBearer

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

Query parameters

pagedoubleOptional>=1Defaults to 1

Page number to retrieve (starts from 1)

sizedoubleOptional1-50Defaults to 15

Number of items to return per page (1-50, default: 15)

customListIdstringOptionalformat: "uuid"

Filter chats by custom list UUID

smartListIdslist of enumsOptional

Filter chats by smart list type(s)

filterlist of enumsOptional

Filter types to apply (can specify multiple via repeated params)

searchstringOptional<=100 characters

Search term to filter chats by user name/handle

sortByenumOptional

Sort order for chat list (default: most_recent_messages)

Allowed values:

Response

List of chats

datalist of objects

Array of chat conversations

paginationobject

Pagination information

Errors

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

Scope required: read:chat

Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.

1	import requests
2
3	url = "https://api.fanvue.com/chats"
4
5	headers = {
6	"X-Fanvue-API-Version": "2025-06-26",
7	"Authorization": "Bearer <token>"
8	}
9
10	response = requests.get(url, headers=headers)
11
12	print(response.json())

1	{
2	"data": [
3	{
4	"createdAt": "2024-01-15T00:00:00.000Z",
5	"lastMessageAt": "2024-01-15T00:00:00.000Z",
6	"isRead": true,
7	"isMuted": true,
8	"unreadMessagesCount": 1.1,
9	"user": {
10	"uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
11	"handle": "sarah-jones",
12	"displayName": "Sarah Jones",
13	"nickname": "SarahK",
14	"isTopSpender": true,
15	"avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
16	"registeredAt": "2024-01-10T12:00:00.000Z"
17	},
18	"lastMessage": {
19	"text": "Hey there! How are you doing?",
20	"type": "SINGLE_RECIPIENT",
21	"uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
22	"sentAt": "2024-01-15T00:00:00.000Z",
23	"hasMedia": true,
24	"mediaType": "image",
25	"senderUuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8"
26	}
27	},
28	{
29	"createdAt": "2024-01-14T00:00:00.000Z",
30	"lastMessageAt": "2023-01-15",
31	"isRead": true,
32	"isMuted": true,
33	"unreadMessagesCount": 1.1,
34	"user": {
35	"uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
36	"handle": "mike-smith",
37	"displayName": "Mike Smithly",
38	"nickname": "string",
39	"isTopSpender": false,
40	"avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
41	"registeredAt": "2024-01-10T12:00:00.000Z"
42	},
43	"lastMessage": {
44	"text": "string",
45	"type": "AUTOMATED_CANCELED",
46	"uuid": "string",
47	"sentAt": "2023-01-15",
48	"hasMedia": true,
49	"mediaType": "image",
50	"senderUuid": "string"
51	}
52	}
53	],
54	"pagination": {
55	"page": 1,
56	"size": 2,
57	"hasMore": false
58	}
59	}

Authentication

Headers

Query parameters

Response

Errors