Overview The Messages module (sdk.messages) handles all OnlyFans messaging functionality including direct messages, mass campaigns, and conversation management.
Direct Messages Send personalized messages with media and pricing
Mass Campaigns Create queued messages for subscriber lists
Chat Management Retrieve chat history and conversations
Direct Messaging Send Chat Message Send a direct message to a specific user with optional media and pricing.
const { data , error } = await sdk . messages . sendChatMessage ({ authentication: { connectionId: "conn_123" }, userId: 123456789 , params: { text: "Hey! Thanks for subscribing! 💕" , mediaItems: [ "/path/to/photo.jpg" , "media_id_123" ], price: 9.99 , // Optional paid message previewMediaCount: 1 // Number of preview media } }) authentication
AuthenticationOptions
required
Either { connectionId: string } or { session: object }
OnlyFans user ID to send message to
Array of media references (paths, URLs, or IDs)
Price for paid messages (in dollars)
Get Chat Messages Retrieve message history with a specific user.
const { data , error } = await sdk . messages . getChatMessages ({ authentication: { connectionId: "conn_123" }, userId: 123456789 , params: { limit: 50 , offset: 0 , query: "search term" // Optional search } }) console . log ( `Found ${ data . list . length } messages` ) Get Specific Message Get details for a specific chat message.
const { data , error } = await sdk . messages . getChatMessage ({ authentication: { connectionId: "conn_123" }, userId: 123456789 , messageId: 789012 }) Mass Messaging Create Queued Message Create a mass message to be sent to multiple users or lists.
const { data , error } = await sdk . messages . createQueuedMessage ({ authentication: { connectionId: "conn_123" }, params: { text: "New content available! 🔥" , mediaItems: [ "/path/to/promo.jpg" ], price: 5.00 , userIds: [ 123 , 456 , 789 ], // Specific users userLists: [ 1 , 2 ], // User list IDs excludeUserLists: [ 3 ], // Exclude these lists scheduledDate: new Date ( "2024-01-25T15:00:00Z" ), // Optional scheduling subscribedAfterDate: new Date ( "2024-01-01" ) // Users who subscribed after this date } }) Array of specific user IDs to send to
Array of user list IDs to send to
Optional scheduled send time
Smart Message Sending Automatically choose between individual or mass messaging.
const { data , error } = await sdk . messages . sendMessage ({ authentication: { connectionId: "conn_123" }, params: { text: "Hello everyone!" , userIds: [ 123456 ], // If single user, sends direct message mediaItems: [ "media_123" ] } }) Get Queued Messages Retrieve your queued/scheduled messages.
const { data , error } = await sdk . messages . getQueueMessages ({ authentication: { connectionId: "conn_123" }, params: { limit: 20 , offset: 0 , type: "scheduled" // "sent", "unsent", "scheduled" } }) Get Specific Queued Message const { data , error } = await sdk . messages . getQueuedMessage ({ authentication: { connectionId: "conn_123" }, queueMessageId: 123456 }) Chat Management Get Chat List Retrieve your active conversations.
const { data , error } = await sdk . messages . getChatsList ({ authentication: { connectionId: "conn_123" }, params: { limit: 20 , order: "recent" , // "recent" or "old" filter: "priority" , // "priority", "who_tipped", "unread" userListId: 123 , query: "search term" } }) Message Management Update Queued Message Modify a queued message before it’s sent.
const { data , error } = await sdk . messages . updateQueuedMessage ({ authentication: { connectionId: "conn_123" }, queueMessageId: 123456 , params: { text: "Updated message text" , scheduledDate: new Date ( "2024-06-01" ) } }) Delete Messages Delete a message (for direct messages, include userId).
// Delete direct message const { data , error } = await sdk . messages . deleteMessage ({ authentication: { connectionId: "conn_123" }, messageId: 123456 , userId: 789 // Required for direct messages }) // Delete queued message const { data , error } = await sdk . messages . deleteMessage ({ authentication: { connectionId: "conn_123" }, messageId: 123456 , isQueuedMessage: true }) Unsend Messages Unsend already sent messages.
// Unsend chat message const { data , error } = await sdk . messages . unsendChatMessage ({ authentication: { connectionId: "conn_123" }, messageId: 123456 , userId: 789 }) // Unsend queued message const { data , error } = await sdk . messages . unsendQueueMessage ({ authentication: { connectionId: "conn_123" }, queueMessageId: 123456 }) Best Practices
Message Quality Engaging Content
Use markdown formatting for rich text
Include relevant media
Personalize messages when possible
Test pricing strategies
Mass Messaging Smart Campaigns
Segment audiences using lists
Schedule messages for optimal times
Monitor delivery and engagement
Respect subscriber preferences
Error Handling Common error scenarios and handling:
const { data , error } = await sdk . messages . sendChatMessage ( params ) if ( error ) { switch ( error . type ) { case "unauthorized" : console . log ( "Session expired" ) break case "forbidden" : console . log ( "Cannot message this user" ) break case "too_many_requests" : console . log ( "Rate limited - wait before sending more" ) break case "bad_request" : console . log ( "Invalid message parameters:" , error . details ) break default : console . log ( "Message failed:" , error . message ) } } Rate Limiting : OnlyFans has strict rate limits for messaging. Space out your messages and use the SDK’s built-in retry logic.
