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_statusreportsconnected: true; the agent receives inbound messages aschannel.messagesignals and replies viachannels_send.
1 maintainer
Metadata
1 maintainer
Release files for kestrel-channel-whatsapp 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| kestrel_channel_whatsapp-0.2.2.tar.gz | 118.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| kestrel_channel_whatsapp-0.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 143.1 kB
Release files / kestrel_channel_whatsapp-0.2.2.tar.gz
| Download URL | kestrel_channel_whatsapp-0.2.2.tar.gz |
|---|---|
| Size | 118.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
68f27bdefec0f65c7080c8888f55926cff90a178c76b0bcee1306516659d8a60
|
|
BLAKE2b-256 checksum How to use checksums |
e22ac1df230f93db9f007e1b86ce7ed2d1abe55c6f7f77a742c68beb147d50aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 4, 2026.
Transparency logRelease files / kestrel_channel_whatsapp-0.2.2-py3-none-any.whl
| Download URL | kestrel_channel_whatsapp-0.2.2-py3-none-any.whl |
|---|---|
| Size | 24.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
97fe09bd1454fd004eb09d216be6c74c4983f620f66fd6673346685a418786ed
|
|
BLAKE2b-256 checksum How to use checksums |
ac0d9c0a649e5af579f637f66a2fe665f6bc2c3655f13ea55091a8cd1469cb97
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 4, 2026.
Transparency log
