Overview

Last updated: April 12, 2026

WhatsApp Module Overview (dwhatsapp)

The dwhatsapp package is the primary mobile gateway for dLANDiscord, utilizing a specialized WhatsApp client to provide AI-powered interactions on mobile devices.

Key Features

  • Multi-Agent Support: Users can interact with different agents (Nikki, Sasha, etc.) in DMs or groups.
  • Sticky Agent Memory: Remembers the last agent used by a specific contact for seamless continuity.
  • Media Handling: Supports image analysis (via multimodal models) and voice note processing (STT/TTS).
  • Single-Shot Mode: Optimized group chat behavior that only triggers on explicit mentions to reduce noise.
  • Dual Output for Voice Notes: Voice notes receive both text AND audio responses in DMs.
  • Image Generation Support: Generated images are properly sent back in response to voice requests.

Voice Note Handling

Processing Pipeline

Voice notes go through a comprehensive pipeline:

Voice Note Received
       ↓
   Download Audio
       ↓
 ProcessVoiceNote() [STT + Agent Detection]
       ↓
 Check Last-Used Agent (sticky memory)
       ↓
 QueryAssistantWithOptions (with Callback)
       ↓
   Text Response Sent First
       ↓
 SanitizeForTTS() [strip emojis/markdown]
       ↓
  GenerateAgentTTS() [Inworld/OpenRouter]
       ↓
   Audio Response Sent
       ↓
 SaveLastUsedAgent() [for continuity]

Dual Output Behavior

For DM voice notes, users receive:

  1. Text Response: Full agent response with emojis and formatting
  2. Voice Note: TTS-generated audio (emojis/markdown stripped)

This ensures accessibility and confirmation of what was said.

Agent Routing Priority

When a voice note is received, agent selection follows this priority:

  1. Explicit Mention: If agent name detected in speech
  2. Last-Used Agent: Previously saved agent for this contact
  3. Contact Preferred Agent: From contacts.json
  4. Default: sysafe (or nikki for MasterAdmin)

Key Files

File Purpose
dwhatsapp/dwhatsapp.go Main client, event handling, voice processing
assistant/voice_handler.go ProcessVoiceNote() for STT and routing
assistant/tts.go TTS generation and sanitization
assistant/nikki_voice.go Voice session state management

Integration Flow

  1. Connection: Authenticates with WhatsApp via QR code or persistent session storage.
  2. Message Event: Listens for incoming messages.
  3. Trigger Detection: Uses ShouldTriggerAI to determine if a response is needed (always on for DMs, mention-based for groups).
  4. Assistant Query: Calls assistant.QueryAssistantWithOptions with platform-specific metadata (WhatsAppID).
  5. Response Delivery: Delivers the agent's text or media response back to the WhatsApp chat.

Mermaid Diagram: WhatsApp Interaction

graph TD
    U[WhatsApp User] --> W[dwhatsapp.go]
    W --> S{Should Trigger AI?}
    S -- Yes --> C[Contact & Role Lookup]
    C --> A[assistant.QueryAssistant]
    A --> LLM[Multimodal / Text Model]
    LLM --> R[Agent Response]
    R --> W
    W --> U
    
    subgraph Voice Processing
        V[Voice Note] --> STT[Speech-to-Text]
        STT --> AD[Agent Detection]
        AD --> AG[Agent Query]
        AG --> TTS[Text-to-Speech]
        TTS --> VA[Voice + Text Output]
    end

Guidance for AI Agents

  • Mobile-Friendly Responses: WhatsApp users are often on mobile. Keep responses concise and use emojis where appropriate for the persona.
  • Media Awareness: You can "see" images and "hear" voice notes sent via WhatsApp. Use this context in your reasoning.
  • Voice Note Responses: When responding to voice notes, your text will also be converted to speech. Keep this in mind for natural conversational flow.

Cross-References