> ## 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.

# BotConfig

> Interface exported by @botmesh/core.

Defined in: [core/provider.ts:1724](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1724)

Options of `new Bot(config)`. Only `provider` is required. Every duration option takes
a string (`'30s'`, `'5m'`) or milliseconds; the constructor validates them and throws
[ConfigValidationError](https://botmesh.afaya.com.co/api/core/classes/ConfigValidationError.md) naming the option.

## Example

```ts theme={null}
import { Bot, MemoryStore } from '@botmesh/core'
import { TelegramProvider } from '@botmesh/telegram'

const bot = new Bot({
  provider: new TelegramProvider({ token: process.env.TELEGRAM_TOKEN! }),
  store: new MemoryStore({ file: './data/store.json' }),
  lang: 'es', // built-in texts in Spanish (default 'en')
  typing: true, // show "typing…" before text replies
})
```

## Properties

### session?

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

Defined in: [core/provider.ts:1725](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1725)

***

### tenantId?

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

Defined in: [core/provider.ts:1727](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1727)

Storage and control-plane namespace. Defaults to `local`.

***

### environmentId?

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

Defined in: [core/provider.ts:1729](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1729)

Deployment environment namespace. Defaults to `default`.

***

### botId?

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

Defined in: [core/provider.ts:1731](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1731)

Stable bot namespace. Defaults to `session` or the provider id.

***

### connectionId?

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

Defined in: [core/provider.ts:1733](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1733)

Stable provider-account/connection namespace. Defaults to `session` or `default`.

***

### persistRaw?

```ts theme={null}
persistRaw?: boolean;
```

Defined in: [core/provider.ts:1735](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1735)

Persist provider-native payloads. Disabled by default to minimize PII.

***

### splitLongText?

```ts theme={null}
splitLongText?: boolean;
```

Defined in: [core/provider.ts:1756](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1756)

Split a `text` send longer than the provider's `capabilities.maxTextLength` (UTF-16
code units) or `capabilities.maxTextBytes` (UTF-8) into several messages, sent in
order at paragraph, line, sentence or word boundaries, never inside a grapheme
(emoji, flags) or the chat's markup (a code block, inline code, a bold run or an HTML
element longer than the limit is closed and reopened; links and URLs stay whole).
`before('send')` hooks run once on the whole text and what they return is split (so
a footer is added once and every part still fits; a hook that makes a short text too
long gets it split too, its explicit key then suffixed from `#1`); an abort skips the
whole text. Each part is then a send of its own: `after('send')` hooks, the message
log and the durable outbox see each part. Only the first part keeps `options.quoted`;
an explicit `idempotencyKey` gets a `#2`, `#3`… suffix from the second part on. The
result is the last part's, with `parts` listing every part. A part that fails rejects
the send and the remaining parts are not sent, except when the durable outbox defers
it (`SendDeferredError`): the remaining parts are then journaled behind it and the
sweeper delivers them too. `bot.enqueue()` journals one record per part (`<key>`,
`<key>#2`…). Edits and `ctx.stream()` (which splits on its own) are not affected, and
the outbox sweeper sends a record as it was journaled. Default `true`; `false` sends
the text as given (the provider may then reject it with `PayloadTooLargeError`).

***

### dedupe?

```ts theme={null}
dedupe?: false | InboundDedupeOptions;
```

Defined in: [core/provider.ts:1766](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1766)

Inbound idempotency: a redelivered message/interaction (webhook retry,
reconnect replay) never runs handlers twice. Keyed by `chatId` + `ref.id`
(interactions: `interactionId`), bounded LRU with optional TTL. Enabled by
default (`{ size: 1000 }`); `false` disables it. Relies on the providers'
INBOUND ID CONTRACT (see `IProvider`). Runs after the access lists: a
blocked delivery is never recorded, so a redelivery after un-blocking is
processed. See `InboundDeduper`.

***

### echoFilter?

```ts theme={null}
echoFilter?: true | EchoFilterOptions;
```

Defined in: [core/provider.ts:1775](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1775)

Echo filter (opt-in): remember the refs of the bot's successful sends (bounded LRU,
optional TTL) and drop an inbound message carrying one of them BEFORE the access
lists, dedupe, journaling and counters — a provider-independent guard for transports
that hand the bot's own messages back without `fromMe` (a mailbox, a gateway, a
`selfId` learned late). `true` = `{ size: 1000 }`. Counted in `metrics().dropped.echo`.
Complements the provider's `fromMe` (the primary guard); omitted = off, as before.

***

### durability?

```ts theme={null}
durability?: DurabilityConfig;
```

Defined in: [core/provider.ts:1783](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1783)

Durable message processing: journal every admitted inbound event before dispatch
(replayed after a crash) and every send in an outbox with idempotency keys, retries,
backoff and a dead-letter queue. Omitted = off (in-memory, exactly as before);
`{}` = on with the in-memory backend. See `DurabilityConfig` and the operations guide.

***

### store?

```ts theme={null}
store?: IStore | StoreKind;
```

Defined in: [core/provider.ts:1791](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1791)

Where chats, contacts, messages and conversation checkpoints are kept: an [IStore](https://botmesh.afaya.com.co/api/core/interfaces/IStore.md)
instance (`new MemoryStore({ file })`, `new SQLiteStore({ file })`, `new RedisStore({ url })`,
…). Default: an in-memory `MemoryStore`. A [StoreKind](https://botmesh.afaya.com.co/api/core/type-aliases/StoreKind.md) string is accepted for
compatibility and means the built-in `MemoryStore`.

***

### ~~storeConfig?~~

```ts theme={null}
storeConfig?: BuiltinStoreConfig;
```

Defined in: [core/provider.ts:1797](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1797)

#### Deprecated

Pass `store: new MemoryStore({ file, maxMessagesPerChat, autoSaveInterval })`
instead. Options of the built-in `MemoryStore`, used only when [BotConfig.store](#store) is not
an `IStore` instance (the bot logs a warning either way).

***

### provider

```ts theme={null}
provider: IProvider;
```

Defined in: [core/provider.ts:1799](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1799)

REQUIRED in v2: the constructed transport provider (BaileysProvider, ...).

***

### commandPrefix?

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

Defined in: [core/provider.ts:1800](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1800)

***

### conversationScope?

```ts theme={null}
conversationScope?: "participant" | "chat";
```

Defined in: [core/provider.ts:1801](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1801)

***

### conversation?

```ts theme={null}
conversation?: object;
```

Defined in: [core/provider.ts:1802](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1802)

#### timeout?

```ts theme={null}
timeout?: string | number;
```

#### timeoutMessage?

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

#### retriesMessage?

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

#### errorMessage?

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

#### cancelledMessage?

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

***

### groupMode?

```ts theme={null}
groupMode?: "all" | "mentions" | "commands";
```

Defined in: [core/provider.ts:1809](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1809)

***

### lang?

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

Defined in: [core/provider.ts:1817](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1817)

Language of the built-in texts (conversation timeouts and retries, wait and form
prompts, slash-command replies) and of `ctx.lang`. Default `'en'`; `'es'` (also
bundled) restores the Spanish texts of the 2.0 alphas. Unlike `i18n.defaultLocale`
it does NOT turn on per-user language resolution (no `ctx.user` read, no provider
language): a single-language bot sets this and nothing else.

***

### i18n?

```ts theme={null}
i18n?: I18nConfig;
```

Defined in: [core/provider.ts:1819](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1819)

Native i18n options (default locale, detector, …). See `bot.locale()`.

***

### handoff?

```ts theme={null}
handoff?: HandoffConfig;
```

Defined in: [core/provider.ts:1821](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1821)

Human handoff behaviour (escape commands, persistence). See `bot.handoff()`.

***

### typing?

```ts theme={null}
typing?: boolean | TypingConfig;
```

Defined in: [core/provider.ts:1828](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1828)

Automatic typing indicator before every text reply sent through `ctx`
(`reply`/`say`/`answer`/`text`/`quote`, and flow `.say`). `true` enables the
defaults (`{ minMs: 800, maxMs: 3000, charsPerSecond: 20 }`). Disabled by default.
Ignored (no indicator, no wait) on providers without `capabilities.typing`.

***

### ~~rateLimit?~~

```ts theme={null}
rateLimit?: unknown;
```

Defined in: [core/provider.ts:1837](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1837)

Ignored: nothing in the core reads it (a v1 leftover; pacing moved to the transports in
v2). Setting it logs a warning when the bot is constructed.

#### Deprecated

Configure pacing on the provider (e.g. `new BaileysProvider({ rateLimit })`)
and the retry of rate-limited `ctx` replies with [BotConfig.rateLimitRetry](#ratelimitretry).
It will be removed in the next major version.

***

### rateLimitRetry?

```ts theme={null}
rateLimitRetry?: false | RateLimitRetryOptions;
```

Defined in: [core/provider.ts:1847](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1847)

In-place retry of a `ctx` send (`reply`/`say`/media in handlers, flows and conversations)
that the transport rejects with a `RateLimitedError` asking for a short wait: the send
waits `retryAfterMs` and is tried again (same payload, hooks not re-run), so a
conversation step does not end on a transient 429. Default `{ retries: 1, maxWaitMs: 5000 }`:
one retry, only when the wait is at most 5 s. A longer wait, other errors and `bot.send()`
fail as before (broadcasts and the durable outbox have their own back-off). `false`
disables it. `retries` counts attempts AFTER the first, like every `retries` option.

***

### debug?

```ts theme={null}
debug?: boolean;
```

Defined in: [core/provider.ts:1849](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1849)

Built-in logger at `debug` level. Without it (and without `logger`) the default level is `warn`.

***

### logIds?

```ts theme={null}
logIds?: "hash" | "raw" | "omit";
```

Defined in: [core/provider.ts:1856](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1856)

How chat and sender ids appear in the bot's own log lines (a phone number or an email
is personal data): `'hash'` (default, HMAC-SHA256 truncated to 16 chars, stable within
the process — the same hashes as the trace spans when `telemetry` is on), `'raw'` (as is,
for local debugging) or `'omit'`. Uses `telemetry.idKey` as the HMAC key when set.

***

### logger?

```ts theme={null}
logger?: LoggerLike;
```

Defined in: [core/provider.ts:1857](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1857)

***

### coordination?

```ts theme={null}
coordination?: CoordinationConfig;
```

Defined in: [core/provider.ts:1865](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1865)

Run this bot as one of N replicas sharing a backend (opt-in). Each chat is processed
by one replica at a time, in ingress order, and an exclusive transport session
(Baileys) is connected by the elected replica only. Omitted: a single process, as
always. See [CoordinationConfig](https://botmesh.afaya.com.co/api/core/interfaces/CoordinationConfig.md) and the "Running N replicas" guide.

***

### scheduler?

```ts theme={null}
scheduler?: SchedulerOptions;
```

Defined in: [core/provider.ts:1874](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1874)

Where durable tasks (`bot.schedule/every/delay(spec, { id }, fn)`) keep their state,
and how replicas share them. Without it, durable tasks use an in-memory store (they
do not survive a restart) and plain tasks behave exactly as before. See
[SchedulerOptions](https://botmesh.afaya.com.co/api/core/interfaces/SchedulerOptions.md).

***

### telemetry?

```ts theme={null}
telemetry?: TelemetryConfig;
```

Defined in: [core/provider.ts:1884](https://github.com/andresayac/botmesh/blob/main/packages/core/src/core/provider.ts#L1884)

Trace the bot's work as spans (inbound message → dispatch → handler / conversation
turn → send; `@botmesh/ai` adds model and tool spans) through a [BotTracer](https://botmesh.afaya.com.co/api/core/interfaces/BotTracer.md) —
OpenTelemetry with `@botmesh/otel`. No message bodies or personal data are recorded;
ids are hashed by default. Omitted: no tracing, the code path is unchanged. See the
"Tracing" guide.


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