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

# IProvider<TRaw>

> Interface exported by @botmesh/core.

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

Transport-agnostic provider contract. `TRaw` is the provider's native raw
payload (proto.IWebMessageInfo, webhook entry, gateway object); it stays
`unknown` in all shared code and is narrowed only inside provider-specific
paths.

STABILITY CONTRACT (normative): for the lifetime of a session, the same
entity MUST yield the same `senderId` and the same chat the same `chatId` on
every emitted event. All transport-internal aliasing is resolved inside the
provider before emission. The core performs no identity reconciliation.

INBOUND ID CONTRACT (normative): a message's `ref.id` and an interaction's
`interactionId` identify ONE logical inbound event within its chat: distinct
events get distinct ids, and a redelivery of the same event (webhook retry,
reconnect replay) carries the same id. Core relies on this for inbound
idempotency (`BotConfig.dedupe`, keyed by `chatId` + id). When the transport
provides no such id, synthesize one from per-event data that a redelivery
repeats (e.g. kind + event timestamp) or emit `''`, which opts the event out
of deduplication. Never fall back to a per-user constant (sender id,
`user_ref`) or a shared placeholder (`'<prefix>_0'`).

## Type Parameters

| Type Parameter | Default type |
| - | - |
|  `TRaw` | `unknown` |

## Properties

### id

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

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

Stable transport tag (e.g. 'baileys', 'telegram') — used to namespace
conversation keys if one Bot ever runs multiple providers concurrently.

***

### capabilities

```ts theme={null}
readonly capabilities: ProviderCapabilities;
```

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

***

### selfId?

```ts theme={null}
readonly selfId?: string | null;
```

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

The bot's own user id once connected (for group mention matching). Optional.

***

### connection?

```ts theme={null}
readonly connection?: unknown;
```

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

A single primary connection handle for DEBUGGING ONLY. Not a structural
guarantee of exactly one connection (Discord may hold many shard sockets).
Core must NOT reach through this for behavior.

## Methods

### start()

```ts theme={null}
start(): Promise<void>;
```

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

#### Returns

`Promise`\<`void`>

***

### stop()

```ts theme={null}
stop(): Promise<void>;
```

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

#### Returns

`Promise`\<`void`>

***

### send()

```ts theme={null}
send(
   chatId, 
   content, 
   options?
): Promise<SendResult<TRaw>>;
```

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

Send normalized content. Rejects with a typed error (section 8) on failure.

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |
| `content` | [`OutboundContent`](https://botmesh.afaya.com.co/api/core/type-aliases/OutboundContent) |
| `options?` | [`SendOptions`](https://botmesh.afaya.com.co/api/core/interfaces/SendOptions) |

#### Returns

`Promise`\<[`SendResult`](https://botmesh.afaya.com.co/api/core/interfaces/SendResult)\<`TRaw`>>

***

### onEvent()

```ts theme={null}
onEvent(listener): () => void;
```

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

Subscribe to the normalized event stream. Returns an unsubscriber.

#### Parameters

| Parameter | Type |
| - | - |
| `listener` | [`InboundListener`](https://botmesh.afaya.com.co/api/core/type-aliases/InboundListener)\<`TRaw`> |

#### Returns

() => `void`

***

### ingest()?

```ts theme={null}
ingest?(rawEvent, headers?): unknown;
```

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

Push ingress for webhook transports (Cloud API POST, Telegram/Discord
webhook, Discord interaction endpoint). The host HTTP server calls this with
the raw body (and, optionally, the request headers for signature checks); the
provider normalizes and emits via onEvent. May return a value the host can
use as the HTTP status (e.g. 200 accepted / 403 bad signature). Socket-first
providers (Baileys, Discord gateway) omit it.

#### Parameters

| Parameter | Type |
| - | - |
| `rawEvent` | `unknown` |
| `headers?` | `Record`\<`string`, `string` \| `string`\[] \| `undefined`> |

#### Returns

`unknown`

***

### downloadMedia()?

```ts theme={null}
downloadMedia?(ref): Promise<Buffer<ArrayBufferLike> | ReadableStream>;
```

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

Lazy media retrieval behind one signature for every download model.

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef) |

#### Returns

`Promise`\<`Buffer`\<`ArrayBufferLike`> | `ReadableStream`>

***

### serializeMediaRef()?

```ts theme={null}
serializeMediaRef?(ref): SerializedMediaRef | undefined;
```

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

Durable journaling (`BotConfig.durability`): turn a live `MediaRef` into a JSON-safe,
versioned reference that [rehydrateMediaRef](#rehydratemediaref) can rebuild in another process, so a
replayed message (crash recovery, background retry) can still download its media.
Synchronous, cheap and side-effect free; a throw counts as "not durable". Return
`undefined` for a ref that must not be journaled (e.g. view-once media). Never include
credentials: the result is stored at rest with the inbound record.

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef) |

#### Returns

[`SerializedMediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/SerializedMediaRef) | `undefined`

***

### rehydrateMediaRef()?

```ts theme={null}
rehydrateMediaRef?(stored, ref): MediaRef | Promise<MediaRef>;
```

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

Rebuild the `MediaRef` of a replayed message from what [serializeMediaRef](#serializemediaref) wrote.
`ref` is the journaled ref without its token. Pure decoding: it must not need the
transport to be connected. `stored` comes from storage and is UNTRUSTED: reject an
invalid, unknown-version or tampered value with a `ProviderError`.

#### Parameters

| Parameter | Type |
| - | - |
| `stored` | [`SerializedMediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/SerializedMediaRef) |
| `ref` | `Omit`\<[`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef), `"token"`> |

#### Returns

[`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef) | `Promise`\<[`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef)>

***

### getMessage()?

```ts theme={null}
getMessage?(ref): Promise<InboundMessage<TRaw> | undefined>;
```

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

Read-back seam for poll aggregation, quote-body resolution, retry decrypt.
Providers that don't need it no-op / omit it. Replaces the constructor-
injected `getMessage` callback baked into BaileysProvider today.

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef) |

#### Returns

`Promise`\<[`InboundMessage`](https://botmesh.afaya.com.co/api/core/interfaces/InboundMessage)\<`TRaw`> | `undefined`>

***

### markRead()?

```ts theme={null}
markRead?(refs): Promise<void>;
```

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

#### Parameters

| Parameter | Type |
| - | - |
| `refs` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef)\[] |

#### Returns

`Promise`\<`void`>

***

### typing()?

```ts theme={null}
typing?(chatId, state?): Promise<void>;
```

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

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |
| `state?` | `"typing"` \| `"paused"` \| `"recording"` |

#### Returns

`Promise`\<`void`>

***

### deleteMessage()?

```ts theme={null}
deleteMessage?(ref): Promise<void>;
```

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

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef) |

#### Returns

`Promise`\<`void`>

***

### editMessage()?

```ts theme={null}
editMessage?(ref, content): Promise<SendResult<TRaw>>;
```

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

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef) |
| `content` | [`OutboundContent`](https://botmesh.afaya.com.co/api/core/type-aliases/OutboundContent) |

#### Returns

`Promise`\<[`SendResult`](https://botmesh.afaya.com.co/api/core/interfaces/SendResult)\<`TRaw`>>

***

### acknowledgeInteraction()?

```ts theme={null}
acknowledgeInteraction?(interactionId, opts?): Promise<void>;
```

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

#### Parameters

| Parameter | Type |
| - | - |
| `interactionId` | `string` |
| `opts?` | \{ `text?`: `string`; `defer?`: `boolean`; } |
| `opts.text?` | `string` |
| `opts.defer?` | `boolean` |

#### Returns

`Promise`\<`void`>

***

### sendDraft()?

```ts theme={null}
sendDraft?(
   chatId, 
   draftId, 
   text, 
   opts?
): Promise<void>;
```

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

Show (or update) an ephemeral, not-yet-sent preview of a message being
generated. Same `draftId` → the same draft is updated in place. A draft is
NOT a message: the caller must still `send()` the final text. Only for
providers with `capabilities.streaming === 'draft'`; rejects (typed error)
where the transport refuses drafts (e.g. Telegram groups), and the caller
then falls back to edits or chunks.

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |
| `draftId` | `number` |
| `text` | `string` |
| `opts?` | [`DraftOptions`](https://botmesh.afaya.com.co/api/core/interfaces/DraftOptions) |

#### Returns

`Promise`\<`void`>

***

### canRenderForm()?

```ts theme={null}
canRenderForm?(form, opts?): boolean;
```

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

Whether a `form` OutboundContent for `form` (and `opts.nativeId`) can be
rendered natively right now, e.g. whether a WhatsApp Flow is mapped to it.
Only consulted when `capabilities.forms === 'native'`; when it returns
`false`, an auto-mode `flow().form()` asks field by field without sending
(and failing) a form message first. Absent = every form is renderable.

#### Parameters

| Parameter | Type |
| - | - |
| `form` | [`FormDefinition`](https://botmesh.afaya.com.co/api/core/interfaces/FormDefinition) |
| `opts?` | \{ `nativeId?`: `string`; } |
| `opts.nativeId?` | `string` |

#### Returns

`boolean`

***

### textFormatFor()?

```ts theme={null}
textFormatFor?(chatId): TextFormat | undefined;
```

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

Rich-text dialect of one chat, for providers that serve several channels
with different markup through one instance (e.g. Twilio: `whatsapp:` chats
render WhatsApp markup, SMS chats render none). Return `undefined` when the
chat's format is unknown; the core then falls back to
`capabilities.textFormat`. Exposed as `ctx.textFormat`. Must be synchronous
and cheap (it runs once per inbound message). Absent = every chat uses
`capabilities.textFormat`.

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |

#### Returns

[`TextFormat`](https://botmesh.afaya.com.co/api/core/type-aliases/TextFormat) | `undefined`


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