<!-- source: https://deepwiki.com/qhkm/zeptoclaw/7.5-whatsapp-integration -->

# WhatsApp Integration

- Cargo.lock
- Cargo.toml
- src/channels/discord.rs
- src/channels/factory.rs
- src/channels/lark.rs
- src/channels/mod.rs
- src/channels/slack.rs
- src/channels/webhook.rs
- src/channels/whatsapp_cloud.rs
- src/cli/channel.rs
- src/providers/gemini.rs

## Purpose and Scope

This document covers ZeptoClaw's WhatsApp integration, which supports two primary implementation strategies to accommodate different use cases, from personal automation to business-scale deployments:

1. WhatsApp Web Native ( WhatsAppWebChannel ) — A native Rust implementation using the wa-rs library. It pairs via QR code and persists session state to a local directory. This is the preferred method for personal accounts and is feature-gated behind the whatsapp-web flag. src/channels/whatsapp_web.rs 1-20 src/channels/factory.rs 118-130
2. WhatsApp Cloud API ( WhatsAppCloudChannel ) — Official Meta WhatsApp Business API integration. It uses webhooks for inbound messages and a REST API for outbound, requiring a Meta Business account. It includes built-in support for audio transcription via TranscriberService . src/channels/whatsapp_cloud.rs 1-13 src/channels/factory.rs 141-163

ZeptoClaw also provides a dedicated `WhatsAppTool` [src/tools/whatsapp.rs14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/whatsapp.rs#L14-L14) to allow agents to proactively send messages or use pre-approved templates through the Cloud API.

**Sources:** [src/channels/factory.rs118-163](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L118-L163) [src/channels/whatsapp_web.rs1-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L1-L20) [src/channels/whatsapp_cloud.rs1-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L1-L13) [src/tools/whatsapp.rs1-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/whatsapp.rs#L1-L14)

## Architecture Overview

ZeptoClaw provides a unified interface for WhatsApp through the `Channel` trait, while abstracting the underlying protocol complexities.

### Multi-Implementation Architecture

```

```

### Feature Comparison

**Sources:** [src/channels/whatsapp_web.rs151-170](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L151-L170) [src/channels/whatsapp_cloud.rs15-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L15-L31) [src/channels/factory.rs118-163](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L118-L163)

## WhatsApp Web (Native) Implementation

The `WhatsAppWebChannel` provides a self-contained integration using the `wa-rs` protocol stack. It is conditionally compiled and only available when the `whatsapp-web` feature is enabled. [src/channels/factory.rs118-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L118-L130)

### Session and Storage

The native channel uses a `SqliteStore` to maintain authentication state across restarts. The database path is configured via `auth_dir` [src/channels/whatsapp_web.rs102-109](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L102-L109) If the directory doesn't exist, it is created automatically during initialization [src/channels/whatsapp_web.rs220-227](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L220-L227)

### Sender Resolution

WhatsApp may deliver messages using LID-based JIDs (e.g., `... @lid`). The channel implements `resolve_sender_phone` to extract the actual phone number from the `sender_alt` field or primary JID for allowlist matching [src/channels/whatsapp_web.rs119-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L119-L132)

### QR Code Rendering

For headless environments, the channel renders the pairing QR code directly in the terminal using Unicode half-block characters (`█`, `▀`, `▄`) [src/channels/whatsapp_web.rs38-80](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L38-L80)

**Sources:** [src/channels/whatsapp_web.rs38-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L38-L132) [src/channels/whatsapp_web.rs220-227](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L220-L227) [src/channels/factory.rs118-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L118-L130)

## WhatsApp Cloud API Implementation

The `WhatsAppCloudChannel` is a high-performance implementation that uses Meta's official Graph API.

### Webhook Handling

The channel starts a dedicated `TcpListener` to receive Meta webhooks [src/channels/whatsapp_cloud.rs24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L24-L24) It handles:

- Verification : Responds to GET challenges from Meta using the configured verify_token src/channels/whatsapp_cloud.rs 400-415
- Inbound Messages : Parses POST notifications into WebhookNotification structures src/channels/whatsapp_cloud.rs 56-63
- Security : Validates requests using HMAC-SHA256 signatures in the X-Hub-Signature-256 header src/channels/whatsapp_cloud.rs 179-204

### Audio Transcription

Unique to the Cloud API implementation is the integration with `TranscriberService` [src/channels/factory.rs149](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L149-L149) When an `audio` message type is received [src/channels/whatsapp_cloud.rs109-112](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L109-L112) the channel can automatically fetch the media from Meta and transcribe it before passing the text to the `MessageBus`.

### Outbound Communication

Outbound messages are sent via HTTPS POST to the Meta Graph API (`/v18.0/{phone_number_id}/messages`) [src/channels/whatsapp_cloud.rs33](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L33-L33) The implementation handles API authentication via a Bearer token [src/channels/whatsapp_cloud.rs448-479](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L448-L479)

**Sources:** [src/channels/whatsapp_cloud.rs24-45](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L24-L45) [src/channels/whatsapp_cloud.rs179-204](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L179-L204) [src/channels/whatsapp_cloud.rs400-415](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L400-L415) [src/channels/factory.rs141-163](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L141-L163)

## Agent Tool: WhatsAppTool

The `WhatsAppTool` allows agents to send messages to any phone number, optionally using pre-approved WhatsApp templates [src/tools/whatsapp.rs77-85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/whatsapp.rs#L77-L85)

### Key Features

- Template Support : Supports template_params for dynamic content injection into pre-approved business templates src/tools/whatsapp.rs 116-150
- Language Localization : Allows overriding the default language code for templates src/tools/whatsapp.rs 128-132
- Validation : Ensures the to parameter contains only digits to prevent API errors src/tools/whatsapp.rs 101-105

### Tool Data Flow

```

```

**Sources:** [src/tools/whatsapp.rs77-162](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/whatsapp.rs#L77-L162) [src/tools/whatsapp.rs181-205](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/whatsapp.rs#L181-L205)

## Message Routing and Security

All WhatsApp implementations share common routing and security logic defined in `BaseChannelConfig`.

### Allowlist Logic

ZeptoClaw enforces a strict allowlist for WhatsApp to prevent unauthorized agent interaction. The logic follows a hierarchical check:

1. If the allowlist is empty and deny_by_default is false , all messages are accepted.
2. If the allowlist contains * , all messages are accepted.
3. Phone numbers are normalized (removing non-digits and suffixes) before comparison src/channels/whatsapp_web.rs 82-91

### Data Flow: Inbound Message

```

```

**Sources:** [src/channels/whatsapp_web.rs82-91](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_web.rs#L82-L91) [src/channels/whatsapp_cloud.rs179-204](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L179-L204) [src/channels/whatsapp_cloud.rs240-270](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/whatsapp_cloud.rs#L240-L270)

## Configuration

### WhatsApp Cloud API Config

The Cloud API requires a `phone_number_id` and an `access_token` (which should be encrypted using `ENC[...]` in the config file) [src/channels/factory.rs143-148](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L143-L148)

```

```

### WhatsApp Web (Native) Config

Requires the `whatsapp-web` feature flag to be active during build [src/channels/factory.rs119](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L119-L119)

```

```

**Sources:** [src/channels/factory.rs118-163](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L118-L163) [src/cli/channel.rs171-203](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/channel.rs#L171-L203) [src/cli/channel.rs240-275](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/channel.rs#L240-L275)
