Bot

Bot is the core of the SDK, encapsulating different platform APIs into a unified format. Different adapters may extend Bot instances with additional properties and methods.

Methods marked with abstract must be implemented by adapter plugins.

Constructor

new Bot(ctx, config, platform)

• ctx: Context context instance
• config: object adapter configuration
• platform: string adapter name

Instance Properties

bot.ctx

• Type: Context

The context instance this Bot belongs to.

bot.config

• Type: object

The configuration used to construct this Bot instance.

bot.adapter

• Type: Adapter

The Adapter instance this Bot belongs to.

bot.platform

• Type: string

The platform name of this Bot.

bot.selfId

• Type: string

The platform account ID of this Bot. Derived from bot.user.id.

bot.user

• Type: User

The user information of this Bot.

bot.status

• Type: Status

The login status of this Bot. Setting this property automatically triggers a login-updated event.

bot.isActive

• Type: boolean

Whether this Bot is active. Returns false when status is OFFLINE or DISCONNECT, otherwise returns true.

bot.internal

• Type: object

The internal interface of this Bot, used to access platform-native APIs.

bot.features

• Type: string[]

The list of API methods supported by this Bot.

bot.hidden

• Type: boolean

Whether this Bot is hidden.

Lifecycle

bot.start()

• Returns: Promise<void>

Start the bot. Sets the status to CONNECT then calls adapter.connect(). If the connection fails, bot.offline() is automatically called to record the error.

This method is automatically called when the context is ready. You usually don't need to call it manually.

bot.stop()

• Returns: Promise<void>

Stop the bot. Sets the status to DISCONNECT then calls adapter.disconnect(), and finally calls bot.offline().

This method is automatically called when the context is disposed. You usually don't need to call it manually.

bot.online()

Set the bot status to ONLINE and clear any error information.

bot.offline(error?)

• error: Error error information

Set the bot status to OFFLINE and record the error information.

bot.dispose()

Remove the bot instance. Removes itself from ctx.bots and triggers a login-removed event.

Session & Events

bot.session(event?)

• event: Partial<Event> event data
• Returns: Session

Create a new session instance. Automatically fills in platform and selfId fields.

bot.dispatch(session)

• session: Session session instance

Dispatch a session event. The session will be distributed through the context's event system.

bot.update(login)

• login: Login login information

Bulk update Bot properties using a Login object. The status property is set last to ensure the login-updated event is dispatched after all properties are updated.

Universal API

Universal APIs are implemented by adapters. They are documented in the corresponding resource pages.

• bot.createMessage()
• bot.createUpload()
• bot.createDirectChannel()
• bot.createChannel()
• bot.getChannel()
• bot.getChannelList()
• bot.getChannelIter()
• bot.updateChannel()
• bot.deleteChannel()
• bot.muteChannel()
• bot.getMessage()
• bot.getMessageList()
• bot.getMessageIter()
• bot.editMessage()
• bot.deleteMessage()
• bot.createReaction()
• bot.deleteReaction()
• bot.clearReaction()
• bot.getReactionList()
• bot.getReactionIter()
• bot.getLogin()
• bot.getUser()
• bot.getFriendList()
• bot.getFriendIter()
• bot.deleteFriend()
• bot.handleFriendRequest()
• bot.getGuild()
• bot.getGuildList()
• bot.getGuildIter()
• bot.handleGuildRequest()
• bot.getGuildMember()
• bot.getGuildMemberList()
• bot.getGuildMemberIter()
• bot.kickGuildMember()
• bot.muteGuildMember()
• bot.handleGuildMemberRequest()
• bot.setGuildMemberRole()
• bot.unsetGuildMemberRole()
• bot.getGuildRoleList()
• bot.getGuildRoleIter()
• bot.createGuildRole()
• bot.updateGuildRole()
• bot.deleteGuildRole()

The *Iter() methods are iterator versions of *List() methods, returning an AsyncIterable that automatically handles pagination.

Internal Routes

bot.defineInternalRoute(path, callback)

• path: string route path
• callback: (request) => Promise<Response> route handler
• Returns: () => void

Define an internal API route. The path supports parameter matching, e.g., /foo/:bar. Returns a dispose function to unregister the route.

bot.getInternalUrl(path, init?, slash?)

• path: string path
• init: URLSearchParams | Record<string, any> query parameters
• slash: boolean whether to use slash format
• Returns: string

Build an internal URL. Default format is internal:{platform}/{selfId}{path}. If slash is true, uses internal/{platform}/{selfId}{path}.