kestrel-channel-whatsapp

WhatsApp messaging channel for Kestrel agents. It runs as an isolated-venv feature: the transport (neonize, which needs protobuf 7 — incompatible with the host's gRPC/Google-AI stack) runs in a per-agent venv and process, and the host talks to it over the SDK's stdio JSON-RPC isolated-feature contract.

It's a single package. The base install is the lightweight host-side marker (SDK only). The transport (neonize/twilio/segno) is the [service] extra, which the host loader installs into a per-agent isolated venv — so the heavy, protobuf-7 deps never touch the host venv:

host venv:           pip install kestrel-channel-whatsapp            # marker, SDK-only
per-agent venv:      pip install "kestrel-channel-whatsapp[service]"  # + transport (done by the loader)

How it integrates

The service advertises a whatsapp channel capability at initialize. The host (kestrel-sovereign ≥ 0.31, the isolated-runtime channel bridge from #1825) registers a forwarding ChannelAdapter into ChannelFeature.registry, so the agent uses the generic channels tools unchanged:

Direction	Path
Outbound	`channels_send(channel="whatsapp", to, message)` → host proxy → service `whatsapp_send` tool → provider
Inbound	provider → service emits a `channel.inbound` event → host proxy → `ChannelFeature.handle_inbound` → `channel.message` cognition signal → agent replies via `channels_send`

Service tools: whatsapp_send, whatsapp_status, whatsapp_link (QR pairing for the web provider).

Providers

Provider	Outbound	Inbound	Notes
`web` (default)	✅	✅	neonize (whatsmeow) — links as a companion device. Scan the `whatsapp_link` QR in WhatsApp → Linked Devices. Needs system `libmagic`.
`twilio`	✅	❌	Outbound-only in the isolated runtime — Twilio inbound needs a public HTTP webhook, which the stdio service does not host. `whatsapp_status` reports `inbound_supported: false`.

A freshly queued message is reported as PENDING, not delivered — the agent will not claim delivery it cannot confirm.

Install

The host installs the [service] extra into a per-agent venv automatically when the feature is enabled. To develop locally:

uv pip install -e /path/to/kestrel-channel-whatsapp            # host-side marker
uv pip install -e "/path/to/kestrel-channel-whatsapp[service]" # + transport, to test the service

Add WhatsAppFeature to the agent's features list in multi_agent.toml, then restart the host. The feature appears in the agent's features UI with a config form.

Configuration

Set via the features UI / persisted config (forwarded to the service through the initialize handshake), or via environment variables (UI/persisted config wins; env is a fallback):

Config key	Env var	Notes
`provider`	`KESTREL_WHATSAPP_PROVIDER`	`web` (default) or `twilio`
`session_db`	`KESTREL_WHATSAPP_SESSION_DB`	web: neonize companion-session SQLite path
`allowed_senders`	—	E.164 allowlist; empty = allow all
`account_sid`	`TWILIO_ACCOUNT_SID`	twilio only
`auth_token`	`TWILIO_AUTH_TOKEN`	twilio only (secret)
`from_number`	`TWILIO_WHATSAPP_FROM`	twilio sender, E.164. Defaults to the sandbox `+14155238886`

Linking the web provider

Enable the feature with provider="web" and restart the host.
Call whatsapp_link (or !whatsapp link) — it returns a pairing QR.
On your phone: WhatsApp → Settings → Linked Devices → Link a Device → scan.
Once linked, whatsapp_status reports connected: true; the agent receives inbound messages as channel.message signals and replies via channels_send.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kestrel_channel_whatsapp-0.2.2.tar.gz (118.5 kB view details)

Uploaded Jul 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

kestrel_channel_whatsapp-0.2.2-py3-none-any.whl (24.6 kB view details)

Uploaded Jul 4, 2026 Python 3

File details

Details for the file kestrel_channel_whatsapp-0.2.2.tar.gz.

File metadata

Download URL: kestrel_channel_whatsapp-0.2.2.tar.gz
Upload date: Jul 4, 2026
Size: 118.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for kestrel_channel_whatsapp-0.2.2.tar.gz
Algorithm	Hash digest
SHA256	`68f27bdefec0f65c7080c8888f55926cff90a178c76b0bcee1306516659d8a60`
MD5	`8d03f64e4fab6b24bcf3d1bdc3a5081d`
BLAKE2b-256	`e22ac1df230f93db9f007e1b86ce7ed2d1abe55c6f7f77a742c68beb147d50aa`

See more details on using hashes here.

Provenance

The following attestation bundles were made for kestrel_channel_whatsapp-0.2.2.tar.gz:

Publisher: publish.yml on KestrelSovereignAI/kestrel-channel-whatsapp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: kestrel_channel_whatsapp-0.2.2.tar.gz
- Subject digest: 68f27bdefec0f65c7080c8888f55926cff90a178c76b0bcee1306516659d8a60
- Sigstore transparency entry: 2072230332
- Sigstore integration time: Jul 4, 2026
Source repository:
- Permalink: KestrelSovereignAI/kestrel-channel-whatsapp@c7114b435331e6ccbb72b16b4cb5206426b2ad61
- Branch / Tag: refs/tags/v0.2.2
- Owner: https://github.com/KestrelSovereignAI
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@c7114b435331e6ccbb72b16b4cb5206426b2ad61
- Trigger Event: push