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

# Instalação

> Instale o zapo-js com npm, pnpm ou yarn, escolha um backend de armazenamento para credenciais e adicione as peer dependencies opcionais que precisar.

<h2 id="requirements">
  Requisitos
</h2>

<Info>
  O `zapo` requer **Node.js `>= 20.9.0`**. O pacote entrega builds duais ESM/CJS e tipos TypeScript completos.
</Info>

<h2 id="install-the-core-package">
  Instale o pacote principal
</h2>

<CodeGroup>
  ```bash npm theme={null}
  npm install zapo-js
  ```

  ```bash pnpm theme={null}
  pnpm add zapo-js
  ```

  ```bash yarn theme={null}
  yarn add zapo-js
  ```
</CodeGroup>

O pacote principal **não tem dependências de runtime obrigatórias**. Todo o resto — armazenamento, logging e o transporte WebSocket — é uma peer dependency opt-in, então você instala apenas o que usa.

<h2 id="the-package-ecosystem">
  O ecossistema de pacotes
</h2>

`zapo-js` é o único install obrigatório. Todo o resto é um pacote opcional `@zapo-js/*` que você adiciona conforme a necessidade:

<Tree>
  <Tree.Folder name="zapo-js — client core, coordinators, contrato de store" defaultOpen>
    <Tree.File name="@zapo-js/store-sqlite — backend SQLite" />

    <Tree.File name="@zapo-js/store-postgres — backend PostgreSQL" />

    <Tree.File name="@zapo-js/store-mysql — backend MySQL" />

    <Tree.File name="@zapo-js/store-redis — backend Redis" />

    <Tree.File name="@zapo-js/store-mongo — backend MongoDB" />

    <Tree.File name="@zapo-js/media-utils — thumbnails, probes, waveforms" />

    <Tree.File name="@zapo-js/voip — chamadas de voz do WhatsApp" />

    <Tree.File name="@zapo-js/wam — paridade de telemetria do WhatsApp Web (analytics)" />

    <Tree.File name="@zapo-js/mcp-server — ferramenta dev: controle por um agente de IA" />

    <Tree.File name="@zapo-js/fake-server — ferramenta dev: servidor de teste in-process" />
  </Tree.Folder>
</Tree>

<h2 id="add-a-storage-backend">
  Adicione um backend de armazenamento
</h2>

O `zapo` persiste o estado de autenticação e do Signal por meio de uma [store](/pt-br/concepts/stores) plugável. Escolha o backend que combina com o seu deployment e instale o pacote dele:

| Pacote                    | Backend                       | Melhor para             |
| ------------------------- | ----------------------------- | ----------------------- |
| `@zapo-js/store-sqlite`   | SQLite (via `better-sqlite3`) | Local / processo único  |
| `@zapo-js/store-postgres` | PostgreSQL                    | Distribuído, relacional |
| `@zapo-js/store-mysql`    | MySQL                         | Distribuído, relacional |
| `@zapo-js/store-redis`    | Redis                         | Cache + persistência    |
| `@zapo-js/store-mongo`    | MongoDB                       | Document store          |

<CodeGroup>
  ```bash SQLite theme={null}
  npm install @zapo-js/store-sqlite better-sqlite3
  ```

  ```bash PostgreSQL theme={null}
  npm install @zapo-js/store-postgres pg
  ```

  ```bash MySQL theme={null}
  npm install @zapo-js/store-mysql mysql2
  ```

  ```bash Redis theme={null}
  npm install @zapo-js/store-redis ioredis
  ```

  ```bash MongoDB theme={null}
  npm install @zapo-js/store-mongo mongodb
  ```
</CodeGroup>

<Note>
  Você também pode rodar sem backend algum — a store em **memória** embutida funciona de imediato e é ótima para testes. Ela apenas não sobrevive a um restart do processo, então você teria que reparear a cada boot.
</Note>

<h2 id="optional-peer-dependencies">
  Peer dependencies opcionais
</h2>

Instale-as apenas se você usar a funcionalidade correspondente:

<CodeGroup>
  ```bash Structured logging theme={null}
  npm install pino pino-pretty
  ```

  ```bash WebSocket proxy theme={null}
  npm install ws
  ```

  ```bash Mobile connections theme={null}
  npm install argo-codec
  ```
</CodeGroup>

* **`pino` + `pino-pretty`** — necessários apenas se você usar [`createPinoLogger`](/pt-br/concepts/configuration#logging). Sem eles, o `ConsoleLogger` embutido é usado.
* **`ws`** — necessário apenas para rotear o WebSocket através de um **proxy**. O `WebSocket` nativo do runtime não consegue receber um `Agent`/dispatcher HTTP, então o `zapo` recorre ao `ws` para a perna `proxy.ws`. Sem um proxy, o `WebSocket` embutido é usado e você não precisa deste pacote.
* **`argo-codec`** — necessário apenas para conexões **mobile** (por enquanto). O fluxo companion padrão (QR / código de pareamento) não o usa.

<h2 id="sending-media">
  Enviando mídia
</h2>

<Warning>
  **O `@zapo-js/media-utils` é efetivamente necessário para enviar mídia utilizável.** A mídia ainda faz upload sem ele, mas não há processor para gerar **thumbnails/previews, dimensões de imagem-vídeo ou waveforms de notas de voz** — então ela pode aparecer como anexo simples ou sem preview. Instale-o sempre que seu app enviar imagens, vídeo, áudio, documentos ou figurinhas.
</Warning>

```bash theme={null}
npm install @zapo-js/media-utils
```

Ele invoca `ffmpeg`/`ffprobe` e usa `sharp`, então garanta que esses binários estejam disponíveis. Veja o [guia de mídia](/pt-br/guides/media#media-processing) para saber como conectar o processador ao client.

<Note>
  `@zapo-js/media-utils` também lista [`file-type`](https://github.com/sindresorhus/file-type) (`^19`) como peer dependency **opcional**. Instale-o (`npm install file-type`) para habilitar a detecção automática de mimetype — sem ele, a [resolução de mimetype do guia de mídia](/pt-br/guides/media#mimetype-resolution) volta a exigir um `mimetype` explícito em cada envio.
</Note>

<h2 id="voice-calls">
  Chamadas de voz
</h2>

Instale [`@zapo-js/voip`](/pt-br/guides/voip) para fazer e receber chamadas de voz do WhatsApp. Ele é distribuído como um plugin de `WaClient` e puxa duas peer dependencies próprias:

```bash theme={null}
npm install @zapo-js/voip @roamhq/wrtc libmlow-wasm
```

* **`@roamhq/wrtc`** — SCTP para o transporte de relay.
* **`libmlow-wasm`** — perfil Opus do WhatsApp, em WebAssembly (sem build nativo).

Veja o [guia de VoIP](/pt-br/guides/voip) para saber como conectar `voipPlugin()` ao client.

<h2 id="telemetry-parity">
  Paridade de telemetria
</h2>

Instale [`@zapo-js/wam`](/pt-br/guides/wam) para que a sessão emita as batches de analytics client-side `w:stats` que uma aba real do WhatsApp Web envia — uma melhoria de paridade de wire / anti-fingerprinting, não obrigatória para mensageria.

```bash theme={null}
npm install @zapo-js/wam
```

A única peer dependency é `zapo-js`. O registry de eventos WAM (`@vinikjkkj/wa-wam`) é fixado como `dependencies` regular do plugin, então vem transitivamente.

Veja o [guia WAM](/pt-br/guides/wam) para saber como conectar `wamPlugin()` ao client. É opt-in: pule-o a menos que você especificamente queira a paridade.

<h2 id="verify-your-setup">
  Verifique sua configuração
</h2>

```ts theme={null}
import { WaClient } from 'zapo-js'

console.log(typeof WaClient) // "function"
```

A seguir, vá para o [quickstart](/pt-br/quickstart) para conectar e enviar sua primeira mensagem.