Skip to main content
SocialAPI lists the direct message (DM) conversations of a connected Bluesky account, reads their messages, and sends text replies. DMs work only when the account’s app password was created with direct message access. Bluesky has no messaging window: you can reply in a conversation at any time. Each send request costs 1 interaction credit, and reads cost none. The cross-platform rules are on Direct messages.

Endpoints

{conversation_id} is the conversation id that GET /v1/inbox/conversations returns. Reactions and typing indicators are not available on Bluesky: see What Bluesky does not support.

Direct message access

A Bluesky app password reaches DMs only when Allow access to your direct messages was ticked when the password was created. Bluesky offers no way to add the option to an existing app password. See Connect an account for the steps. Without that access:
  • POST /v1/inbox/conversations/{conversation_id}/messages returns 403 platform.bluesky.dm_scope_missing, and the request still costs its interaction credit.
  • The conversation list stays empty, and a sync started with POST /v1/inbox/sync ends in state: failed with an error that says the app password has no direct message access.
  • Posts, comments, and mentions keep working.
To turn DMs on, create a new app password with the option ticked, then send POST /v1/accounts/connect again with the same handle, the new password, and the account’s brand_id. Connecting again with the old password does not help.

Your first message

List the conversations of the account:
Response (HTTP 200):
Send a reply into that conversation:
Response (HTTP 200):
message_ids holds the SocialAPI ID of the sent message. The message appears in the conversation on Bluesky once the call returns.

Conversations on Bluesky

The conversation fields are in Conversations. On Bluesky: A group conversation appears as one conversation with one participant: the first member Bluesky lists that is not the connected account. The other members are not returned. Each sync loads the 100 most recently active conversations. A conversation outside them appears once a new message moves it into them. A conversation already listed stays listed.

New conversations and messages

Bluesky sends SocialAPI no notification of new messages, so SocialAPI sends no dm.received event for a Bluesky account. To pick up what arrived, start a sync with POST /v1/inbox/sync:
  • With only account_id, the sync refreshes the conversation list, including the latest message of each conversation, and loads the messages of conversations never loaded before, as described in the guide.
  • With conversation_id as well, it loads the new messages of that conversation.
The first GET /v1/inbox/conversations/{conversation_id}/messages returns the conversation’s latest messages. After that, a new incoming message appears only after POST /v1/inbox/sync with that conversation_id. If more than 100 messages arrive between two syncs, the older ones are missing. Each target accepts 1 sync you start every 5 minutes: a second attempt after the first sync finished and inside that time returns 429 inbox.sync_rate_limited with a Retry-After header. See Refresh the inbox manually.
Response (HTTP 202):

Read messages

GET /v1/inbox/conversations/{conversation_id}/messages lists the messages of a conversation, newest first, with the fields in Read messages. On Bluesky:
  • platform_id is Bluesky’s message ID, and sender_id is the sender’s DID.
  • attachment_type, attachment_url, and reply_to are null on every message read from Bluesky: SocialAPI reads only the text of a Bluesky message. A message you sent through SocialAPI with an attachment keeps its attachment_type and attachment_url in the list, although Bluesky received an empty message.
  • A conversation’s history starts with its 100 most recent messages. Older messages are not available.
  • Bluesky reports no delivery or read receipts, so the status of an outgoing message does not change after the send.

Send a message

POST /v1/inbox/conversations/{conversation_id}/messages sends the text of the request as a Bluesky message. The request fields are in Send a message. On Bluesky: SocialAPI turns no link, hashtag, or @handle in a DM into a link or mention: the text is sent as plain text. A request costs 1 interaction credit. When the allowance is used up, the call returns 429 validation.interaction_limit_exhausted. When the conversation is locked on Bluesky, the call returns 503 platform.bluesky.ConvoLocked and the credit stays spent. The credit comes back only when the call fails with a validation.* error: see When a credit comes back.

What Bluesky does not support

  • Reactions. POST and DELETE /v1/inbox/conversations/{conversation_id}/messages/{message_id}/reaction return 501 resource.not_supported.
  • Typing indicators and seen receipts. POST /v1/inbox/conversations/{conversation_id}/sender-action returns 501 resource.not_supported. POST /v1/inbox/conversations/{conversation_id}/read returns { "success": true }, and the person sees nothing.
  • Attachments and interactive content. Text only. Each attachment is sent as an extra empty message.
  • Starting a conversation. SocialAPI sends only into a conversation that exists on Bluesky and appears in GET /v1/inbox/conversations.
  • A private reply to a comment. Bluesky has no comment-to-DM path: see Bluesky comments.

Limits

Errors and debugging

Check these in order when a Bluesky DM call fails:
  1. 401, 403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks the scope in Scopes.
  2. 403 platform.bluesky.dm_scope_missing. The app password has no direct message access: see Direct message access.
  3. 403 account.permission_missing. The account lacks the messages.read or messages.write permission. error.meta.permission names it.
  4. 404 conversation.not_found. The conversation is not yours, or belongs to another connected account than account_id.
  5. 400 validation.field_invalid with error.meta.field set to app_password. Bluesky no longer accepts the saved app password, for example because it was deleted in Bluesky settings. Create a new app password and connect the account again.
  6. 403 account.reconnection_required, 401 platform.bluesky.auth. Bluesky rejected the saved credential. Connect the account again.
  7. 403 platform.bluesky.account_takedown. Bluesky suspended the account. Connecting again does not restore access.
  8. 400 validation.*. The body is wrong: error.meta.field names the field, and for validation.platform_param error.message carries Bluesky’s reason. A field_invalid on app_password is step 5.
  9. 422 messaging.tag_not_supported. The request sent message_tag. Remove it.
  10. 503 platform.bluesky.ConvoLocked. The conversation is locked on Bluesky.
  11. 429 platform.bluesky.rate_limit. Bluesky’s limit is used up. Wait, then retry.
  12. 429 validation.interaction_limit_exhausted. Your plan’s interaction allowance is used up: see Plans and usage.
  13. 429 inbox.sync_rate_limited. A second sync of the same target within 5 minutes of the last one you started, after it finished. Wait for the seconds in Retry-After.
  14. 501 resource.not_supported. A reaction, a typing indicator, or a seen receipt.
  15. 503 platform.bluesky.api_error. The request to Bluesky failed, or Bluesky answered with no error name. Retry.
Any other Bluesky refusal returns 503 platform.bluesky.{error}, where {error} is Bluesky’s error name, and error.message carries Bluesky’s reason. Bluesky’s own codes are in Errors: Bluesky, and the DM codes in Errors.

Scopes

Events

SocialAPI sends no dm.* event for a Bluesky account: no dm.received, no dm.sent, and no dm.status.*. Read new messages with a sync, as in New conversations and messages. See Bluesky webhook events.

Use from an AI agent

There is no tool for inbox sync. See MCP tools.
Last modified on November 15, 2026