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

# Evolution API

[Evolution API](https://github.com/EvolutionAPI/evolution-api) v2, a
self-hosted WhatsApp REST gateway built on Baileys. Outbound: REST with the
`apikey` header. Inbound: the instance webhook, authenticated with a shared
secret header or Evolution's `jwt_key` (HS256 JWT).

## Install

```bash theme={null}
pnpm add @botmesh/core @botmesh/evolution
```

## Usage

```ts theme={null}
import { EvolutionProvider } from '@botmesh/evolution'

const provider = new EvolutionProvider({
  baseUrl: 'http://localhost:8080',
  apiKey: process.env.EVOLUTION_API_KEY!,
  instance: 'my-instance',
  webhookSecret: process.env.EVOLUTION_WEBHOOK_SECRET!, // or webhookJwtKey
})
// POST /webhook/evolution → res.sendStatus(provider.ingest(body, headers))
```

* `start()` checks the instance; when it is not paired, the QR or pairing
  code arrives in the `connection` update (`authPayload`).
* LID/PN twins sent by Evolution are reconciled before emitting; pass
  `identityPersistence` to keep ids stable across restarts.
* Polls, reactions, edits (text), typing and read receipts; buttons, lists
  and cards degrade to numbered text; `template` is rejected, and so is a
  poll WhatsApp cannot carry (fewer than 2 or more than 12 options, empty or
  repeated ones).
* If Evolution stops offering QR codes before the number is paired
  (`QRCODE_LIMIT`), the `connection` update is `closed` with reason
  `sessionInvalid`: call `start()` again for a new QR.
* Keep the instance webhook's `webhookByEvents` off: with it, Evolution adds
  the event name to the URL and an exact-path route answers 404.

## Next steps

* [Channels](https://botmesh.afaya.com.co/guide/channels.md): choosing a channel, the capability matrix and the cross-channel contract.
* [WPPConnect](https://botmesh.afaya.com.co/guide/wppconnect.md): the other self-hosted gateway, sharing `@botmesh/wa-gateway-kit`.
* [Webhook server](https://botmesh.afaya.com.co/guide/server.md): mount the provider with `@botmesh/server`.
* [Package README](https://github.com/andresayac/botmesh/tree/main/packages/evolution-provider)


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