> ## Documentation Index
> Fetch the complete documentation index at: https://botmesh.afaya.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# BotEvents

> Interface exported by @botmesh/core.

Defined in: [core/Bot.ts:118](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L118)

Events the bot emits, by name, with their payload type. Listen with
`bot.on(name, listener)`, e.g. `bot.on('ready', () => …)` or `bot.on('error', (err) => …)`.

## Properties

### ready

```ts theme={null}
ready: void;
```

Defined in: [core/Bot.ts:120](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L120)

Emitted once the provider's connection state reaches `'ready'`.

***

### qr

```ts theme={null}
qr: string;
```

Defined in: [core/Bot.ts:122](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L122)

Emitted with the provider's auth artifact (QR string / pairing code / OAuth URL).

***

### connection

```ts theme={null}
connection: ConnectionUpdate;
```

Defined in: [core/Bot.ts:124](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L124)

Emitted on every provider connection-state transition.

***

### message

```ts theme={null}
message: MessageContext;
```

Defined in: [core/Bot.ts:126](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L126)

Emitted after every dispatched inbound message finishes its pipeline.

***

### error

```ts theme={null}
error: object;
```

Defined in: [core/Bot.ts:128](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L128)

Emitted for any internal/handler error.

#### error

```ts theme={null}
error: unknown;
```

#### ctx?

```ts theme={null}
ctx?: MessageContext<DefaultTools, unknown>;
```

***

### started

```ts theme={null}
started: void;
```

Defined in: [core/Bot.ts:130](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L130)

Emitted once `start()` finishes.

***

### stopping

```ts theme={null}
stopping: void;
```

Defined in: [core/Bot.ts:136](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L136)

Emitted once per `stop()` of a running bot, right after inbound is closed and BEFORE the
drain and the transport stop: cancel long work here (model calls, downloads) while the
transport can still deliver what is in flight. A throwing listener is reported on `'error'`.

***

### stopped

```ts theme={null}
stopped: void;
```

Defined in: [core/Bot.ts:138](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L138)

Emitted once `stop()` finishes.

***

### command:unknown

```ts theme={null}
"command:unknown": object;
```

Defined in: [core/Bot.ts:140](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L140)

Emitted by the Dispatcher for an unrecognized `/xyz` command.

#### ctx

```ts theme={null}
ctx: MessageContext;
```

#### command

```ts theme={null}
command: string;
```

***

### reaction

```ts theme={null}
reaction: InboundReaction;
```

Defined in: [core/Bot.ts:142](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L142)

Forwarded provider event: someone reacted to a message.

***

### poll

```ts theme={null}
poll: PollVote;
```

Defined in: [core/Bot.ts:144](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L144)

Forwarded provider event: a poll's aggregated votes changed.

***

### call

```ts theme={null}
call: CallEvent;
```

Defined in: [core/Bot.ts:146](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L146)

Forwarded provider event: a call notification.

***

### group

```ts theme={null}
group: GroupEvent;
```

Defined in: [core/Bot.ts:148](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L148)

Forwarded provider event: group participants changed.

***

### presence

```ts theme={null}
presence: PresenceEvent;
```

Defined in: [core/Bot.ts:150](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L150)

Forwarded provider event: a contact's presence changed.

***

### status

```ts theme={null}
status: DeliveryStatus;
```

Defined in: [core/Bot.ts:152](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L152)

Forwarded provider event: outbound delivery/read receipt.

***

### handoff

```ts theme={null}
handoff: HandoffState;
```

Defined in: [core/Bot.ts:154](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L154)

A chat was handed off to a human (`bot.handoff()` / `ctx.handoff()`).

***

### resume

```ts theme={null}
resume: ResumeEvent;
```

Defined in: [core/Bot.ts:156](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L156)

A handed-off chat was given back to the bot (`bot.resume()`).

***

### conversation:started

```ts theme={null}
"conversation:started": ConversationStartedEvent;
```

Defined in: [core/Bot.ts:158](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L158)

A conversation/flow was entered (trigger match, `bot.trigger()`, dormant resume, `c.goto()`).

***

### conversation:ended

```ts theme={null}
"conversation:ended": ConversationEndedEvent;
```

Defined in: [core/Bot.ts:160](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L160)

A conversation/flow ended — completed, cancelled, timed out, out of retries or errored.

***

### coordination:leader

```ts theme={null}
"coordination:leader": object;
```

Defined in: [core/Bot.ts:162](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L162)

Multi-replica (`coordination`): this replica was elected for a singleton (`provider:<id>`) and starts it.

#### name

```ts theme={null}
name: string;
```

#### fence

```ts theme={null}
fence: number;
```

***

### coordination:follower

```ts theme={null}
"coordination:follower": object;
```

Defined in: [core/Bot.ts:164](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L164)

Multi-replica: this replica lost (or gave up) a singleton leadership and stands by.

#### name

```ts theme={null}
name: string;
```

#### reason?

```ts theme={null}
reason?: LeaseLossReason;
```

***

### coordination:lease-lost

```ts theme={null}
"coordination:lease-lost": LeaseInfo & object;
```

Defined in: [core/Bot.ts:166](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L166)

Multi-replica: a chat turn or leadership was lost before its release (pause, partition, backend down).

#### Type Declaration

##### reason

```ts theme={null}
reason: LeaseLossReason;
```

***

### coordination:handover

```ts theme={null}
"coordination:handover": ConversationHandoverEvent;
```

Defined in: [core/Bot.ts:171](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L171)

Multi-replica (`coordination.handover`): a conversation another replica ran was taken
over on this one — resumed, or handled by the hand-over fallback (see `outcome`).

***

### durability:dead

```ts theme={null}
"durability:dead": object;
```

Defined in: [core/Bot.ts:176](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L176)

Durability (`BotConfig.durability`): an inbound event or a send was dead-lettered after its
retries (`id` is the inbox record id or the outbox key). Replay/retry it through `bot.durability`.

#### kind

```ts theme={null}
kind: "inbound" | "outbound";
```

#### id

```ts theme={null}
id: string;
```

#### chatId?

```ts theme={null}
chatId?: string;
```

#### error

```ts theme={null}
error: unknown;
```

***

### durability:ambiguous

```ts theme={null}
"durability:ambiguous": object;
```

Defined in: [core/Bot.ts:181](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/Bot.ts#L181)

Durability: a send's outcome is unknown after a crash (the provider was called, the result
was never recorded). Handled per `durability.outbox.onAmbiguous`.

#### key

```ts theme={null}
key: string;
```

#### chatId

```ts theme={null}
chatId: string;
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.