Skip to main content
Este guia ajudará você a criar um bot simples do WhatsApp que responde a mensagens. Você aprenderá os conceitos principais e terá um bot funcionando ao final.

Exemplo básico

Aqui está um bot mínimo que responde a mensagens “ping”:
src/main.rs

Passo a passo detalhado

1

Configure o backend de armazenamento

O bot precisa de armazenamento persistente para dados de sessão, chaves e estado:
Isso cria um arquivo de banco SQLite chamado whatsapp.db no diretório atual. A sessão será persistida entre reinicializações.
2

Configure o builder do bot

O padrão Bot::builder() permite que você configure todos os componentes obrigatórios:
Todos os quatro componentes (backend, transporte, cliente HTTP, runtime) são obrigatórios. O builder usa um padrão typestate — seu código não compilará se algum estiver faltando.
3

Trate eventos

Use .on_event() para tratar eventos que chegam do WhatsApp:
O manipulador de eventos recebe dois parâmetros:
  • event: Um Arc<Event> — use &*event ou event.as_ref() para fazer pattern-matching no tipo interno do evento
  • client: Um Arc<Client> que você pode usar para enviar mensagens ou chamar métodos da API
4

Construa e execute o bot

Construa o bot e inicie o loop de eventos:
O duplo .await? é intencional:
  • O primeiro .await? inicia o bot e retorna um BotHandle
  • O segundo .await? aguarda o bot terminar a execução

Respondendo a mensagens

Vamos estender o bot para responder “pong” a mensagens “ping”:

Métodos principais

  • msg.text_content() - Extrai o texto de qualquer tipo de mensagem (conversation, extended text, etc.)
  • client.send_message() - Envia uma mensagem para um chat
  • info.source.chat - O JID (identificador) do chat de onde a mensagem veio
  • info.source.sender - O JID do usuário que enviou a mensagem

Métodos de autenticação

Pareamento por QR code (padrão)

O bot gera automaticamente códigos QR quando não está autenticado. Escaneie com seu celular para vincular:

Pair code (número de telefone)

Alternativamente, vincule usando um número de telefone e um código de 8 dígitos:
PairCodeOptions deriva companion_platform_id e companion_platform_display do PlatformType do dispositivo por padrão (Chrome com Chrome (Linux) para o perfil web padrão). Você pode sobrescrever o id no wire quando necessário:
platform_id aceita o enum no wire CompanionWebClientType (ids ASCII de um único byte). A string de exibição é sempre derivada — não há um campo separado platform_display.
A autenticação por pair code e por QR code rodam simultaneamente. O método que for concluído primeiro será o usado.

Executando o bot

1

Primeira execução - Autenticação

Na primeira execução, o bot irá gerar um QR code:
Escaneie o QR code com o WhatsApp no seu celular:
  1. Abra o WhatsApp no seu celular
  2. Vá em Configurações → Aparelhos conectados
  3. Toque em “Conectar um aparelho”
  4. Escaneie o QR code exibido no seu terminal
2

Execuções seguintes - Login automático

Após o pareamento, a sessão é salva. O bot irá reconectar automaticamente:
Você deverá ver:
3

Teste o bot

Envie “ping” para o seu bot de qualquer chat do WhatsApp. Ele deve responder com “pong”!

Flags de CLI do exemplo de demonstração

O repositório inclui um exemplo de bot de demonstração (examples/demo.rs) que suporta argumentos de CLI para autenticação:
O bot de demonstração responde a 🦀ping com uma resposta citada 🏓 Pong!, edita a resposta para anexar a latência de envio e suporta ping/pong de mídia via reuso de CDN.

Usando MessageContext

Para um tratamento de mensagens mais limpo, use MessageContext para encapsular a mensagem, os metadados e o cliente juntos. Isso fornece métodos convenientes como send_message (que mira automaticamente o chat de origem), build_quote_context, edit_message e revoke_message:
Em seguida, defina funções de tratamento focadas:

Encaminhamento de mídia com reuso de CDN

Você também pode encaminhar mídia instantaneamente reusando os campos originais do CDN — sem necessidade de download ou re-upload:
Construir uma mensagem com um campo de sub-mensagem (como image_message abaixo) requer MessageField. O whatsapp-rust reexporta buffa como whatsapp_rust::buffa (e MessageField diretamente do prelude), então não é mais necessário adicionar buffa ao seu Cargo.toml.
Veja o guia de encaminhamento de mídia para mais detalhes.

Exemplo completo com logging

Aqui está um exemplo pronto para produção com logging adequado, reações, edição de mensagens e reuso de CDN para mídia:
src/main.rs

Configurando alvos de log

whatsapp-rust usa o crate log com alvos específicos por módulo para filtragem detalhada. Você pode usar RUST_LOG para controlar quais componentes emitem saída de log.

Alvos de log disponíveis

Exemplos de filtragem

Durante o desligamento ou desconexão, o cliente automaticamente rebaixa erros de sincronização do nível error para debug para reduzir ruído. Isso significa que você não verá logs de erro espúrios quando o cliente estiver se desconectando intencionalmente.

Executando com Docker

Você também pode executar o bot usando Docker em vez de compilar localmente:
Os dados da sessão são armazenados no diretório /data dentro do contêiner. Monte um volume para persisti-los entre reinicializações. O contêiner é desligado graciosamente em docker stop — o bot se desconecta limpamente do WhatsApp antes de sair. Veja o guia de instalação para mais detalhes.

Benchmarking

O repositório inclui um exemplo de benchmark em examples/benchmark.rs que você pode usar para testes rápidos de desempenho em nível de integração. Ele usa um backend em memória e suporta uma URL de WebSocket personalizada via a variável de ambiente WHATSAPP_WS_URL:
O exemplo de benchmark requer a feature flag danger-skip-tls-verify porque foi projetado para uso com servidores de teste locais.
Para benchmarks de integração mais abrangentes com rastreamento de alocações, a suíte bench-integration mede cenários do mundo real (conectar, enviar, receber, reconectar) e reporta o tempo de relógio e contagens de alocação no heap por operação:
Para benchmarks de protocolo de baixo nível, o crate wacore inclui uma suíte de benchmarks com iai-callgrind que mede contagens de instruções para o pipeline completo de envio/recebimento (mensagens DM e em grupo com várias contagens de participantes), codificação do protocolo binário, operações do Signal Protocol e geração de tokens de reporte:
Veja a documentação dos benchmarks do wacore para detalhes sobre cada suíte, otimizações de alocação e integração com CI.

Próximos passos

Enviando mensagens

Aprenda sobre os diferentes tipos de mensagem e como enviá-los

Manipulação de mídia

Faça upload e download de imagens, vídeos e documentos

Gerenciamento de grupos

Crie e gerencie grupos do WhatsApp

Referência da API Client

Explore todos os métodos disponíveis do cliente