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 O manipulador de eventos recebe dois parâmetros:
.on_event() para tratar eventos que chegam do WhatsApp:event: UmArc<Event>— use&*eventouevent.as_ref()para fazer pattern-matching no tipo interno do eventoclient: UmArc<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 umBotHandle - 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 chatinfo.source.chat- O JID (identificador) do chat de onde a mensagem veioinfo.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:
- Abra o WhatsApp no seu celular
- Vá em Configurações → Aparelhos conectados
- Toque em “Conectar um aparelho”
- 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:
🦀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, useMessageContext 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:
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.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 cratelog 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:/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 emexamples/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.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:
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:
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