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}/messagesreturns403 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/syncends instate: failedwith anerrorthat says the app password has no direct message access. - Posts, comments, and mentions keep working.
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: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 nodm.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_idas well, it loads the new messages of that conversation.
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.
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_idis Bluesky’s message ID, andsender_idis the sender’s DID.attachment_type,attachment_url, andreply_toarenullon every message read from Bluesky: SocialAPI reads only the text of a Bluesky message. A message you sent through SocialAPI with an attachment keeps itsattachment_typeandattachment_urlin 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
statusof 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.
POSTandDELETE /v1/inbox/conversations/{conversation_id}/messages/{message_id}/reactionreturn501 resource.not_supported. - Typing indicators and seen receipts.
POST /v1/inbox/conversations/{conversation_id}/sender-actionreturns501 resource.not_supported.POST /v1/inbox/conversations/{conversation_id}/readreturns{ "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:401,403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks the scope in Scopes.403 platform.bluesky.dm_scope_missing. The app password has no direct message access: see Direct message access.403 account.permission_missing. The account lacks themessages.readormessages.writepermission.error.meta.permissionnames it.404 conversation.not_found. The conversation is not yours, or belongs to another connected account thanaccount_id.400 validation.field_invalidwitherror.meta.fieldset toapp_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.403 account.reconnection_required,401 platform.bluesky.auth. Bluesky rejected the saved credential. Connect the account again.403 platform.bluesky.account_takedown. Bluesky suspended the account. Connecting again does not restore access.400 validation.*. The body is wrong:error.meta.fieldnames the field, and forvalidation.platform_paramerror.messagecarries Bluesky’s reason. Afield_invalidonapp_passwordis step 5.422 messaging.tag_not_supported. The request sentmessage_tag. Remove it.503 platform.bluesky.ConvoLocked. The conversation is locked on Bluesky.429 platform.bluesky.rate_limit. Bluesky’s limit is used up. Wait, then retry.429 validation.interaction_limit_exhausted. Your plan’s interaction allowance is used up: see Plans and usage.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 inRetry-After.501 resource.not_supported. A reaction, a typing indicator, or a seen receipt.503 platform.bluesky.api_error. The request to Bluesky failed, or Bluesky answered with no error name. Retry.
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 nodm.* 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.
Related
- Bluesky API: connect the account with an app password that has DM access
- Bluesky comments: replies to your posts
- Direct messages: the endpoints and fields shared by every platform
- Unified inbox: the sync endpoint and its states
- Errors: every Bluesky error code