class Bot

extends EventEmitter

A bot that can interact with the Bluesky API.

Constructor

constructor(options?)

Create a new bot.

Parameters

options: BotOptions = {}

Configuration options.

Properties

readonly api: AtpServiceClient

The Bluesky API client, with rate-limited methods.

chatProxy?: AtpAgent

The proxy agent for chat-related requests.

langs: string[]

The default list of languages to attach to posts.

profile: Profile

The bot account's Bluesky profile.

Methods

login(options)

Log in with an identifier and password.

Parameters

options: BotLoginOptions

The bot account's identifier and password.

Returns

Promise<ComAtprotoServerCreateSession.OutputSchema>

Session data.

resumeSession(session)

Resume an existing session.

Parameters

session: AtpSessionData

Session data.

Returns

Promise<ComAtprotoServerGetSession.OutputSchema>

Updated session data.

getPost(uri, options?)

Fetch a post by its AT URI.

Parameters

uri: string

The post's AT URI.

options: BotGetPostOptions = {}

Optional configuration.

Returns

Promise<Post>

getPosts(uris, options?)

Fetch up to 25 posts by their AT URIs.

Parameters

uris: string[]

The URIs of the posts to fetch.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<Post[]>

getUserPosts(did, options?)

Fetch up to 100 (default 100) posts by a user's DID.

Parameters

did: string

The user's DID.

options: BotGetUserPostsOptions = {}

Optional configuration.

Returns

Promise<{ cursor: string | undefined; posts: Post[]; }>

The user's posts and, if there are more posts to fetch, a cursor.

getUserLikes(did, options?)

Fetch up to 100 (default 100) posts liked by a user.

Parameters

did: string

The user's DID.

options: BotGetUserLikesOptions = {}

Optional configuration.

Returns

Promise<{ cursor: string | undefined; posts: Post[]; }>

getProfile(didOrHandle, options?)

Fetch a profile by DID or handle.

Parameters

didOrHandle: string

The user's DID or handle.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<Profile>

getList(uri, options?)

Fetch a list by its AT URI.

Parameters

uri: string

The list's AT URI.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<List>

getUserLists(did, options)

Fetch all (up to 100, default 100) lists created by a user.

Parameters

did: string

The user's DID.

options: BotGetUserListsOptions

Optional configuration.

Returns

Promise<{ cursor: string | undefined; lists: List[]; }>

getFeedGenerator(uri, options?)

Fetch a feed generator by its AT URI.

Parameters

uri: string

The feed generator's AT URI.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<FeedGenerator>

getFeedGenerators(uris, options?)

Fetch a list of feed generators by their AT URIs.

Parameters

uris: string[]

The URIs of the feed generators to fetch.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<FeedGenerator[]>

getTimeline(options?)

Get the bot's home timeline.

Parameters

options: BotGetTimelineOptions = {}

Optional configuration.

Returns

Promise<Post[]>

getLabeler(did, options?)

Fetch a labeler by its account DID.

Parameters

did: string

The DID of the labeler to fetch.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<Labeler>

getLabelers(dids, options?)

Fetch a list of labelers by their account DIDs.

Parameters

dids: string[]

The DIDs of the labelers to fetch.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<Labeler[]>

getConversationForMembers(members, options?)

Fetch a conversation containing 1-10 members. If a conversation doesn't exist, it will be created.

Parameters

members: string[]

The DIDs of the conversation members.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<Conversation>

getConversation(id, options?)

Fetch a conversation by its ID.

Parameters

id: string

The conversation's ID.

options: BaseBotGetMethodOptions = {}

Optional configuration.

Returns

Promise<Conversation>

listConversations(options?)

Fetch all conversations the bot is a member of.

Parameters

options: BotListConversationsOptions = {}

Optional configuration.

Returns

Promise<{ conversations: Conversation[]; cursor: string | undefined; }>

getConversationMessages(conversationId, options?)

Fetch the message history for a conversation.

Parameters

conversationId: string

The ID of the conversation to fetch messages for.

options: BotGetConversationMessagesOptions = {}

Optional configuration.

Returns

Promise<{ cursor: string | undefined; messages: ChatMessage | DeletedChatMessage[]; }>

An array of messages and a cursor for pagination.

post(payload, options?)

Create a post.

Parameters

payload: PostPayload

The post payload.

options: BotPostOptions = {}

Optional configuration.

Returns

Promise<PostReference>

A reference to the created post.

deletePost(uri)

Delete a post.

Parameters

uri: string

The post's AT URI.

like(reference)

Like a post or feed generator.

Parameters

reference: StrongRef

The post or feed generator to like.

Returns

Promise<StrongRef>

The like record's AT URI and CID.

unlike(uri)

Delete a like.

Parameters

uri: string

The liked record's AT URI or the like record's AT URI.

repost(reference)

Repost a post.

Parameters

reference: StrongRef

The post to repost.

Returns

Promise<StrongRef>

The repost record's AT URI and CID.

deleteRepost(uri)

Delete a repost.

Parameters

uri: string

The post's AT URI or the repost record's AT URI.

follow(did)

Follow a user.

Parameters

did: string

The user's DID.

Returns

Promise<StrongRef>

The follow record's AT URI and CID.

unfollow(didOrUri)

Delete a follow.

Parameters

didOrUri: string

The user's DID or the follow record's AT URI.

mute(did)

Mute a user.

Parameters

did: string

The user's DID.

unmute(did)

Delete a mute.

Parameters

did: string

The user's DID.

block(did)

Block a user.

Parameters

did: string

The user's DID.

Returns

Promise<StrongRef>

The block record's AT URI and CID.

unblock(didOrUri)

Delete a block.

Parameters

didOrUri: string

The user's DID or the block record's AT URI.

sendMessage(payload, options?)

Send a message in a DM conversation.

Parameters

payload: ChatMessagePayload

The message payload.

options: BotSendMessageOptions = {}

Optional configuration.

Returns

Promise<ChatMessage>

The sent message.

sendMessages(payload, options?)

Send up to 100 private messages at once.

Parameters

payload: ChatMessagePayload[]

The messages payload.

options: BotSendMessageOptions = {}

Optional configuration.

Returns

Promise<ChatMessage[]>

The sent messages.

leaveConversation(id)

Leave a DM conversation.

Parameters

id: string

The conversation's ID.

label(options)

Label a user or record. Note that you need a running Ozone instance on this DID to publish labels!

See also: Self-hosting Ozone

Parameters

options: BotLabelRecordOptions

Information on the label to apply.

negateLabels(options)

Negate labels previously applied to a record by the bot.

Parameters

options: BotLabelRecordOptions

Information on the record to negate labels on.

addLabeler(did)

Subscribe to a labeler.

Parameters

did: string

The labeler's DID.

removeLabeler(did)

Unsubscribe from a labeler.

Parameters

did: string

The labeler's DID.

resolveHandle(handle)

Resolve a handle to a DID.

Parameters

handle: string

The handle to resolve.

Returns

Promise<string>

The user's DID.

updateHandle(handle)

Update the bot's handle.

Parameters

handle: string

The new handle.

declareLabeler(policies)

Declare that the bot account is a labeler. This will allow the bot to publish labels, and allow other users to subscribe to the bot as a labeler. Note that you need an active Ozone instance running on this DID to be able to publish labels!

See also: - Labeler declarations - Self-hosting Ozone

Parameters

policies: AppBskyLabelerDefs.LabelerPolicies

The labeler's policies; a description of the labels the bot will publish.

deleteLabelerDeclaration()

Delete the bot's labeler declaration record.

setChatPreference(preference)

Set the bot's preference for who can initiate a new chat conversation. This does not affect existing conversations.

Parameters

preference: IncomingChatPreference

The new preference.

createRecord(nsid, record, rkey?)

Create a record.

Parameters

nsid: string

The collection's NSID.

record: object

The record to create.

rkey?: string

The rkey to use.

Returns

Promise<StrongRef>

The record's AT URI and CID.

putRecord(nsid, record, rkey)

Put a record in place of an existing record.

Parameters

nsid: string

The collection's NSID.

record: object

The record to put.

rkey: string

The rkey to use.

Returns

Promise<StrongRef>

The record's AT URI and CID.

deleteRecord(uri)

Delete a record.

Parameters

uri: string

The record's AT URI.

Overload 1/10

on(event, listener)

Emitted when the bot begins listening for events.

Parameters

event: "open"
listener: () => void

Returns

this

on(event, listener)

Emitted when an error occurs while listening for events.

Parameters

event: "error"
listener: (error: unknown) => void

Returns

this

on(event, listener)

Emitted when the bot stops listening for events.

Parameters

event: "close"
listener: () => void

Returns

this

on(event, listener)

Emitted when the bot receives a reply.

Parameters

event: "reply"
listener: (post: Post) => void

Returns

this

on(event, listener)

Emitted when the bot receives a quote post.

Parameters

event: "quote"
listener: (post: Post) => void

Returns

this

on(event, listener)

Emitted when the bot is mentioned.

Parameters

event: "mention"
listener: (post: Post) => void

Returns

this

on(event, listener)

Emitted when one of the bot's posts is reposted.

Parameters

event: "repost"
listener: (event: { post: Post; uri: string; user: Profile; }) => void

A callback function that receives the post that was reposted, the user who reposted it, and the repost's AT URI.

Returns

this

on(event, listener)

Emitted when one of the bot's posts is liked.

Parameters

event: "like"
listener: (event: { post: Post; uri: string; user: Profile; }) => void

A callback function that receives the post that was liked, the user who liked it, and the like's AT URI.

Returns

this

on(event, listener)

Emitted when the bot is followed.

Parameters

event: "follow"
listener: (event: { uri: string; user: Profile; }) => void

A callback function that receives the user who followed the bot and the follow's AT URI.

Returns

this

on(event, listener)

Emitted when the bot receives a message in a DM conversation.

Parameters

event: "message"
listener: (message: ChatMessage) => void

A callback function that receives the message.

Returns

this

Overload 1/10

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "open"
listener: () => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "error"
listener: (error: unknown) => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "close"
listener: () => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "reply"
listener: (post: Post) => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "quote"
listener: (post: Post) => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "mention"
listener: (post: Post) => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "repost"
listener: (event: { post: Post; uri: string; user: Profile; }) => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "like"
listener: (event: { post: Post; uri: string; user: Profile; }) => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "follow"
listener: (event: { uri: string; user: Profile; }) => void

Returns

this

addListener(event, listener)

Alias for Bot#on.

Parameters

event: "message"
listener: (message: ChatMessage) => void

Returns

this

off(event, listener)

Remove an event listener.

Parameters

event: string

The event to remove the listener for.

listener: (args: any[]) => void

The listener callback to remove.

Returns

this

removeListener(event, listener)

Alias for Bot#off.

Parameters

event: string
listener: (args: any[]) => void

Returns

this

removeAllListeners(event?)

Remove all event listeners, or those of the specified event.

Parameters

event?: string

The event to remove listeners for.

Returns

this