Skip to main content

​
Pré-requisitos

Antes de instalar whatsapp-rust, certifique-se de ter:
  • Rust nightly (padrão) — necessário para a edição Rust 2024 e o protocolo binário otimizado com SIMD. O projeto fixa nightly-2026-04-05 via rust-toolchain.toml. Veja Usando Rust stable se você precisa de suporte ao toolchain 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

Adicione whatsapp-rust e suas dependências necessárias ao seu Cargo.toml:

​
Feature flags

whatsapp-rust suporta diversas features opcionais:
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: Para usar whatsapp-rust em um ambiente de navegador WASM, habilite a feature js em wacore:
Cargo.toml
O crate waproto tem suas próprias feature flags: 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
O crate whatsapp-rust-sqlite-storage tem suas próprias feature flags: Para usar um SQLite instalado no sistema em vez da versão empacotada:
Cargo.toml
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

Por padrão, whatsapp-rust usa a edição Rust 2024 e habilita a feature simd, que usa a API portable_simd do Rust para codificação/decodificação otimizada do protocolo binário. Ambos exigem um toolchain Rust nightly. O projeto fixa nightly-2026-04-05 via rust-toolchain.toml. Para compilar com Rust stable, desabilite a feature simd definindo default-features = false. Você deve fazer isso em ambos whatsapp-rust e wacore — caso contrário, a unificação de features do Cargo irá reabilitar SIMD através da dependência wacore:
Cargo.toml
Definir default-features = false somente em whatsapp-rust não é suficiente se você também depende de wacore diretamente. A dependência direta de wacore habilita simd por padrão, e o Cargo mescla features entre todos os dependentes. Ambos precisam optar por sair.
O codificador/decodificador faz fallback automaticamente para caminhos escalares quando o SIMD está desabilitado. Não há diferença funcional — apenas uma pequena diferença de desempenho nas operações do protocolo binário.

​
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

​
Verifique a instalação

Crie um arquivo de teste simples para verificar a instalação:
src/main.rs
Execute com:
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

O processo de build:
  1. Usa rust:alpine com cargo-chef (fixado em uma versão específica com --locked) para cache eficiente e reproduzível de dependências
  2. 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
  3. 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
  4. Faz cache da compilação de dependências via cargo chef cook --target em uma camada separada para rebuilds rápidos
  5. Produz uma imagem final a partir de scratch contendo apenas o binário

​
Execute o contêiner

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:

​
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