Instalação - WhatsApp Rust

Pré-requisitos

Antes de instalar whatsapp-rust, certifique-se de ter:

Rust 1.94 ou mais novo — o MSRV do workspace, e todas as features padrão compilam com Rust stable. Veja Usando Rust stable.
Gerenciador de pacotes Cargo

O SQLite é empacotado por padrão com o crate whatsapp-rust-sqlite-storage, então você não precisa instalá-lo separadamente. Se preferir vincular ao SQLite instalado no sistema, desabilite a feature padrão bundled-sqlite.

Adicione ao seu projeto

whatsapp-rust reexporta a pilha inteira (wacore, wacore_binary, waproto e todas as implementações incluídas), então uma linha de dependência basta para a maioria dos projetos:

Cargo.toml

[dependencies]
whatsapp-rust = "0.7"
# Só é preciso declarar um crate irmão para features específicas dele:
# whatsapp-rust-sqlite-storage = "0.7"
# whatsapp-rust-tokio-transport = "0.7"
# whatsapp-rust-ureq-http-client = "0.7"
# wacore = "0.7"
# waproto = "0.7"
tokio = { version = "1.53", features = ["macros", "rt-multi-thread"] }

Todo caminho de sub-crate é alcançável pelo crate principal — whatsapp_rust::waproto::whatsapp (apelidado como wa no prelude), whatsapp_rust::wacore, whatsapp_rust::wacore_binary, whatsapp_rust::store::SqliteStore, whatsapp_rust::http::UreqHttpClient e whatsapp_rust::transport::TokioWebSocketTransportFactory. O mesmo vale para os crates de terceiros cujos tipos aparecem na API pública (anyhow, async_trait, bytes, chrono, futures, serde, serde_json, async_channel, buffa): você nunca precisa adicioná-los nem fixar suas versões.

Feature flags

whatsapp-rust suporta diversas features opcionais:

Feature	Descrição	Incluída por padrão
`tokio-runtime`	Habilita a implementação `TokioRuntime` do trait `Runtime`. Também necessária para `TypedCache::invalidate_all()` em backends de cache personalizados	✅ Sim
`tokio-native`	Runtime Tokio multi-thread (`tokio/rt-multi-thread`)	✅ Sim
`tokio-transport`	Transporte WebSocket Tokio	✅ Sim
`ureq-client`	Cliente HTTP Ureq	✅ Sim
`sqlite-storage`	Backend de armazenamento SQLite	✅ Sim
`signal`	Manipulação de sinais Unix (desligamento gracioso em SIGTERM/Ctrl+C)	✅ Sim
`tracing`	Emite spans/eventos `tracing` em connect, send, receive, IQ, app state, pareamento, mídia e fluxos de sessão. Veja Observabilidade	❌ Não
`tracing-pii`	Mostra números de telefone crus nos campos do `tracing` em vez do `pn#<token>` redigido. Apenas para depuração local — nunca habilite em produção	❌ Não
`metrics`	Emite contadores, histogramas e gauges `wa_*` pela fachada `metrics`. Veja Métricas	❌ Não
`client-lifecycle`	Seam de ciclo de vida de extensões com escopo de geração (`ClientLifecycle`, `ConnectionScope`). Habilitada automaticamente por `plugins`	❌ Não
`plugins`	Host nativo de plugins em tempo de build: registro tipado de `ClientPlugin` via `ClientBuilder`, APIs com escopo de capacidade e ciclo de vida de tarefas por geração. Habilita `client-lifecycle` (veja Plugins nativos)	❌ Não
`voip`	Chamadas de voz e vídeo 1:1, perfil completo: adaptadores MLow + libopus, plano de vídeo H.264 neutro de codec, criptografia E2E-SRTP e transporte por relay. Alias para `voip-mlow` + `voip-libopus` (veja Chamadas VoIP)	❌ Não
`voip-runtime`	Feature base interna habilitada por toda feature `voip-*` (driver Tokio, transporte por relay, DTLS/SCTP). Não é para ser nomeada diretamente — escolha `voip-encoded` ou uma feature de codec	❌ Não
`voip-encoded`	Perfil `voip` mais estreito: apenas transporte por relay e a fronteira de áudio codificado, sem codec embutido — forneça pacotes Opus/MLOW do seu próprio encoder/decoder	❌ Não
`voip-mlow`	`voip-encoded` mais o codec MLOW puro-Rust embutido	❌ Não
`voip-libopus`	`voip-encoded` mais o adaptador de codec opcional libopus via FFI	❌ Não
`legacy-session-interop`	Interop tipada com o modelo decodificado do `SessionRecord` v1 legado do libsignal, para migrar estado de autenticação produzido externamente	❌ Não
`danger-skip-tls-verify`	Pula a verificação TLS (inseguro)	❌ Não
`danger-skip-cert-chain-verify`	Pula a checagem da cadeia de certificados no handshake Noise (inseguro)	❌ Não
`debug-snapshots`	Snapshots de protocolo para debug	❌ Não

Todas as features padrão habilitam Tokio como o runtime assíncrono, mas todo componente é opcional. Para usar um runtime diferente (async-std, WASM, etc.), desabilite todos os padrões e forneça suas próprias implementações dos traits Runtime, TransportFactory, HttpClient e Backend. Veja backends personalizados para detalhes.

O crate wacore tem uma feature adicional para alvos de navegador WASM:

Feature	Descrição	Incluída por padrão
`js`	Habilita geração de números aleatórios compatível com navegador via `getrandom/wasm_js` para alvos `wasm32`	❌ Não

Para usar whatsapp-rust em um ambiente de navegador WASM, habilite a feature js em wacore:

Cargo.toml

[dependencies]
wacore = { version = "0.7", default-features = false, features = ["js"] }

O crate waproto tem suas próprias feature flags:

Feature	Descrição	Incluída por padrão
`serde-deserialize`	Adiciona o derive `Deserialize` e `#[serde(default)]` a todos os tipos protobuf	❌ Não
`serde-snake-case`	Aceita nomes de variantes de enum em snake_case durante a desserialização (implica `serde-deserialize`)	❌ Não
`serde-enum-repr`	Enums são (de)serializados pela representação numérica em vez do nome da variante — o que a ponte JS/WASM e o serializador camelCase esperam	❌ Não

O build.rs sempre executa e gera whatsapp.rs no OUT_DIR — nenhuma feature flag é necessária para builds normais. Todos os tipos protobuf derivam Serialize por padrão. Habilite serde-deserialize quando precisar analisar tipos protobuf a partir de JSON (por exemplo, em uma ponte WASM). Habilite serde-snake-case quando sua fonte JSON usa snake_case para variantes de enum (buffa gera SCREAMING_SNAKE_CASE por padrão).

Cargo.toml

[dependencies]
waproto = { version = "0.7", features = ["serde-snake-case"] }

O crate whatsapp-rust-sqlite-storage tem suas próprias feature flags:

Feature	Descrição	Incluída por padrão
`bundled-sqlite`	Empacota o SQLite (compila a partir do código-fonte, sem biblioteca de sistema necessária)	✅ Sim

Para usar um SQLite instalado no sistema em vez da versão empacotada:

Cargo.toml

[dependencies]
whatsapp-rust-sqlite-storage = { version = "0.7", default-features = false }

O whatsapp-rust já distribuiu um histórico de conversas/mensagens opcional, o whatsapp-rust-chat-store. Nós o extraímos para seu próprio repositório, já que materializar um fluxo de eventos em conversas, prévias e contadores de não lidas é uma decisão de aplicação, não de protocolo. Ele não é mais distribuído a partir de whatsapp-rust — o link será adicionado aqui assim que o repositório substituto for publicado.

As features padrão fornecem tudo que é necessário para a maioria dos casos de uso. Personalize features somente se tiver requisitos específicos.

Usando Rust stable

whatsapp-rust usa a edição Rust 2024 e declara um MSRV de 1.94, ambos suportados pelo Rust stable, e o conjunto de features padrão não tem nenhuma dependência exclusiva do nightly — cargo build/cargo add whatsapp-rust funciona com Rust stable de fábrica, sem precisar desabilitar nenhuma feature.

O rust-toolchain.toml do próprio projeto ainda fixa um compilador nightly (nightly-2026-06-16), mas apenas para flags de build internas focadas em tamanho de binário — -Zshare-generics e linking lld/ICF, definidas para todo o workspace em .cargo/config.toml, mais -Zbuild-std somente para o build da imagem Docker (veja a seção de implantação com Docker abaixo) — não para nenhuma feature de linguagem que os crates publicados precisem. Essa fixação rege a compilação do workspace whatsapp-rust em si; ela não afeta seu projeto quando você depende de whatsapp-rust via crates.io ou git.

Suporte a alvos de 32 bits

whatsapp-rust usa portable-atomic em vez de std::sync::atomic para operações atômicas de 64 bits. Isso significa que a biblioteca funciona em alvos de 32 bits (ARM32, MIPS, RISC-V 32, etc.) onde AtomicU64 não está disponível nativamente — portable-atomic fornece um fallback em software automaticamente. Nenhuma configuração extra é necessária. A dependência portable-atomic é incluída com a feature fallback habilitada por padrão em todos os crates (whatsapp-rust, wacore e whatsapp-rust-sqlite-storage).

Se você está compilando para um alvo embarcado de 32 bits ou fazendo compilação cruzada para armv7-unknown-linux-gnueabihf, whatsapp-rust irá compilar e rodar corretamente sem ajustes.

Exemplo com features personalizadas

Se você quiser usar apenas features específicas:

Cargo.toml

[dependencies]
whatsapp-rust = { version = "0.7", default-features = false, features = ["sqlite-storage", "tokio-transport"] }

Verifique a instalação

Crie um arquivo de teste simples para verificar a instalação:

src/main.rs

use whatsapp_rust::bot::Bot;

fn main() {
    println!("whatsapp-rust installed successfully!");
}

Execute com:

cargo run

Se você vir “whatsapp-rust installed successfully!”, está pronto para seguir para o guia Início rápido.

Implantação com Docker

whatsapp-rust inclui um Dockerfile para construir uma imagem de contêiner mínima e estaticamente vinculada. O build multi-estágio produz uma imagem baseada em scratch contendo apenas o binário compilado.

Construa a imagem

docker build -t whatsapp-rust .

O processo de build:

Usa rust:alpine com cargo-chef (fixado em uma versão específica com --locked) para cache eficiente e reproduzível de dependências
Detecta a triple de alvo do host em tempo de build — docker buildx build --platform linux/arm64 produz binários nativos sem alterações no Dockerfile
Habilita -Zshare-generics=y (−5,6% no .text) e recompila std com o perfil de release (-Zbuild-std, −~300 KiB adicionais) para participar do LTO gordo — juntas, essas duas flags reduzem o .text em cerca de 8%; a série completa de otimizações (#842–#845) alcançou 15% no total
Faz cache da compilação de dependências via cargo chef cook --target em uma camada separada para rebuilds rápidos
Produz uma imagem final a partir de scratch contendo apenas o binário

Execute o contêiner

docker run -v ./data:/data whatsapp-rust

O contêiner usa /data como seu diretório de trabalho, então monte um volume lá para persistir seu banco SQLite e dados de sessão entre reinicializações. Para autenticação via pair code, passe a flag --phone:

docker run -v ./data:/data whatsapp-rust --phone 15551234567

Desligamento gracioso

O contêiner suporta desligamento gracioso sem configuração adicional. Quando a feature signal está habilitada (e está, por padrão), o bot escuta por SIGTERM e Ctrl+C, desconecta-se limpamente do WhatsApp e sai. O Docker envia SIGTERM em docker stop, então o bot encerra graciosamente sem perder o estado da sessão. Como a imagem é construída a partir de scratch, o PID 1 é o próprio binário. Ele lida com sinais diretamente — nenhum sistema init como tini é necessário.

O Dockerfile detecta a triple de alvo do host em tempo de build via rustc -vV, então docker buildx build --platform linux/arm64 (ou qualquer outra plataforma suportada) funciona nativamente sem modificar o Dockerfile. As flags de build exclusivas do nightly (-Zshare-generics, -Zbuild-std) se aplicam apenas dentro desta imagem — consumidores stable e invocações locais de cargo build não são afetados.

Próximos passos

Início rápido

Crie seu primeiro bot do WhatsApp em minutos

​Pré-requisitos

​Adicione ao seu projeto

​Feature flags

​Usando Rust stable

​Suporte a alvos de 32 bits

​Exemplo com features personalizadas

​Verifique a instalação

​Implantação com Docker

​Construa a imagem

​Execute o contêiner

​Desligamento gracioso

​Próximos passos

Início rápido

Pré-requisitos

Adicione ao seu projeto

Feature flags

Usando Rust stable

Suporte a alvos de 32 bits

Exemplo com features personalizadas

Verifique a instalação

Implantação com Docker

Construa a imagem

Execute o contêiner

Desligamento gracioso

Próximos passos