Skip to main content

​
Overview

Postiz integrates with Bluesky (and other ATProto networks) to post text, images, and videos with rich text formatting and facets.
Two-Factor Authentication Not Supported: Disable 2FA on your Bluesky account before connecting. Use app-specific passwords instead.

​
Authentication

Bluesky uses custom authentication with app passwords.
1

Generate App Password

Go to Bluesky Settings → App Passwords → Create New
2

Connect in Postiz

Enter your Bluesky credentials:
  • Service URL (usually https://bsky.social)
  • Identifier (handle or email)
  • App password
3

Credentials Encrypted

Credentials are encrypted and stored securely

​
Custom Fields

  • Default: https://bsky.social
  • Supports custom ATProto instances
  • Must be valid HTTPS URL
  • Your Bluesky handle (e.g., user.bsky.social)
  • Or email address
  • Used for login
  • Use app-specific password (not main password)
  • Minimum 3 characters
  • Stored encrypted

​
Supported Features

​
Content Types

  • Maximum: 300 characters
  • Rich text with facets (links, mentions)
  • Automatic link detection
  • Mention autocomplete
Media Rules:
  • Maximum 1 video OR maximum 4 pictures
  • Cannot mix images and videos
  • Posts can be text-only without attachments

​
Rich Text & Facets

Bluesky automatically detects and creates facets for:
  • URLs: Automatically linked
  • Mentions: @username.bsky.social format
  • Hashtags: May be supported in future
const rt = new RichText({
  text: "Check out @user.bsky.social and https://example.com"
});
await rt.detectFacets(agent);
// Automatically creates link and mention facets

​
Media Processing

​
Image Optimization

Images are automatically optimized:
1

Fetch Image

Download image from provided URL
2

Check Size

If over 976KB, reduce dimensions
3

Resize Iteratively

Reduce by 10% until under limit
4

Upload

Upload optimized image as blob
Images are resized while preserving aspect ratio until they fit Bluesky’s size limits.

​
Video Upload

Video upload is more complex:
1

Get Service Auth

Request authentication for video service
2

Upload Video

Upload to video.bsky.app with auth token
3

Monitor Job

Poll job status every 30 seconds
4

Get Blob Reference

Receive blob reference when complete
Video processing can take several minutes for large files.

​
Replies & Threads

Create threaded conversations:
1

Main Post

Create initial post
2

Reply

Reference parent post’s URI and CID
3

Thread Chain

Maintains root and parent references
{
  text: "Reply text",
  reply: {
    root: {
      uri: "at://did:plc:xxx/app.bsky.feed.post/xxx",
      cid: "bafyxxx"
    },
    parent: {
      uri: "at://did:plc:xxx/app.bsky.feed.post/yyy",
      cid: "bafyyyy"
    }
  }
}

​
Automation Features

​
Auto-Repost High-Performing Posts

{
  identifier: 'bluesky-autoRepostPost',
  settings: {
    likesAmount: 100,
    runEveryMilliseconds: 21600000,  // 6 hours
    totalRuns: 3
  }
}
Automatically reposts when post reaches like threshold.

​
Auto-Plug Posts

Add promotional replies to successful posts: 
{
  identifier: 'bluesky-autoPlugPost',
  settings: {
    likesAmount: 50,
    post: "Your promotional message"
  }
}

​
Mentions

Search and mention users: 
GET /mention?query=username

Returns:
[
  {
    id: "user.bsky.social",
    label: "User Display Name",
    image: "https://cdn.bsky.app/avatar..."
  }
]
Mentions are formatted as @handle.

​
Rate Limits

Bluesky Rate Limits:
  • 2 concurrent posting jobs
  • Moderate rate limits
  • Video processing takes time
  • No strict daily limits

​
Best Practices

Character Limit

Keep posts under 300 characters - concise content performs best

Image Quality

Use high-quality images - they’re compressed automatically

Video Format

Vertical 9:16 videos work well for mobile viewing

Threading

Use threads for longer content to improve engagement

​
Troubleshooting

If authentication fails:
  • Verify you’re using an app password (not main password)
  • Check handle is correct (include .bsky.social)
  • Ensure 2FA is disabled
  • Try generating new app password
Video upload issues:
  • Check video is MP4 format
  • Verify file size isn’t too large
  • Ensure video URL is accessible
  • Processing can take several minutes
  • Job state FAILED means encoding error
If images fail:
  • Automatic compression should handle this
  • Check source image isn’t corrupted
  • Try reducing image dimensions manually
  • Maximum ~976KB after compression
Session issues:
  • Bluesky tokens need periodic refresh
  • Re-login automatically attempted
  • If refresh fails, reconnect account
  • Check credentials are still valid

Build docs developers (and LLMs) love

Get started for freeTalk to us