BotConfig - botmesh

Defined in: core/provider.ts:1724 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 naming the option.

Example

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?

session?: string;

Defined in: core/provider.ts:1725

tenantId?

tenantId?: string;

Defined in: core/provider.ts:1727 Storage and control-plane namespace. Defaults to local.

environmentId?

environmentId?: string;

Defined in: core/provider.ts:1729 Deployment environment namespace. Defaults to default.

botId?

botId?: string;

Defined in: core/provider.ts:1731 Stable bot namespace. Defaults to session or the provider id.

connectionId?

connectionId?: string;

Defined in: core/provider.ts:1733 Stable provider-account/connection namespace. Defaults to session or default.

persistRaw?

persistRaw?: boolean;

Defined in: core/provider.ts:1735 Persist provider-native payloads. Disabled by default to minimize PII.

splitLongText?

splitLongText?: boolean;

Defined in: core/provider.ts:1756 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?

dedupe?: false | InboundDedupeOptions;

Defined in: core/provider.ts:1766 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?

echoFilter?: true | EchoFilterOptions;

Defined in: core/provider.ts:1775 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?

durability?: DurabilityConfig;

Defined in: core/provider.ts:1783 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?

store?: IStore | StoreKind;

Defined in: core/provider.ts:1791 Where chats, contacts, messages and conversation checkpoints are kept: an IStore instance (new MemoryStore({ file }), new SQLiteStore({ file }), new RedisStore({ url }), …). Default: an in-memory MemoryStore. A StoreKind string is accepted for compatibility and means the built-in MemoryStore.

storeConfig?

storeConfig?: BuiltinStoreConfig;

Defined in: core/provider.ts:1797

Deprecated

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

provider

provider: IProvider;

Defined in: core/provider.ts:1799 REQUIRED in v2: the constructed transport provider (BaileysProvider, …).

commandPrefix?

commandPrefix?: string;

Defined in: core/provider.ts:1800

conversationScope?

conversationScope?: "participant" | "chat";

Defined in: core/provider.ts:1801

conversation?

conversation?: object;

Defined in: core/provider.ts:1802

timeout?

timeout?: string | number;

timeoutMessage?

timeoutMessage?: string;

retriesMessage?

retriesMessage?: string;

errorMessage?

errorMessage?: string;

cancelledMessage?

cancelledMessage?: string;

groupMode?

groupMode?: "all" | "mentions" | "commands";

Defined in: core/provider.ts:1809

lang?

lang?: string;

Defined in: core/provider.ts:1817 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?

i18n?: I18nConfig;

Defined in: core/provider.ts:1819 Native i18n options (default locale, detector, …). See bot.locale().

handoff?

handoff?: HandoffConfig;

Defined in: core/provider.ts:1821 Human handoff behaviour (escape commands, persistence). See bot.handoff().

typing?

typing?: boolean | TypingConfig;

Defined in: core/provider.ts:1828 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?

rateLimit?: unknown;

Defined in: core/provider.ts:1837 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. It will be removed in the next major version.

rateLimitRetry?

rateLimitRetry?: false | RateLimitRetryOptions;

Defined in: core/provider.ts:1847 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?

debug?: boolean;

Defined in: core/provider.ts:1849 Built-in logger at debug level. Without it (and without logger) the default level is warn.

logIds?

logIds?: "hash" | "raw" | "omit";

Defined in: core/provider.ts:1856 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?

logger?: LoggerLike;

Defined in: core/provider.ts:1857

coordination?

coordination?: CoordinationConfig;

Defined in: core/provider.ts:1865 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 and the “Running N replicas” guide.

scheduler?

scheduler?: SchedulerOptions;

Defined in: core/provider.ts:1874 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.

telemetry?

telemetry?: TelemetryConfig;

Defined in: core/provider.ts:1884 Trace the bot’s work as spans (inbound message → dispatch → handler / conversation turn → send; @botmesh/ai adds model and tool spans) through a BotTracer — 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.

​Example

​Properties

​session?

​tenantId?

​environmentId?

​botId?

​connectionId?

​persistRaw?

​splitLongText?

​dedupe?

​echoFilter?

​durability?

​store?

​storeConfig?

​Deprecated

​provider

​commandPrefix?

​conversationScope?

​conversation?

​timeout?

​timeoutMessage?

​retriesMessage?

​errorMessage?

​cancelledMessage?

​groupMode?

​lang?

​i18n?

​handoff?

​typing?

​rateLimit?

​Deprecated

​rateLimitRetry?

​debug?

​logIds?

​logger?

​coordination?

​scheduler?

​telemetry?

Example

Properties

session?

tenantId?

environmentId?

botId?

connectionId?

persistRaw?

splitLongText?

dedupe?

echoFilter?

durability?

store?

storeConfig?

Deprecated

provider

commandPrefix?

conversationScope?

conversation?

timeout?

timeoutMessage?

retriesMessage?

errorMessage?

cancelledMessage?

groupMode?

lang?

i18n?

handoff?

typing?

rateLimit?

Deprecated

rateLimitRetry?

debug?

logIds?

logger?

coordination?

scheduler?

telemetry?