Enhance ADK Connector documentation with WhatsApp support#1916
Conversation
Updated the ADK Connector documentation to include WhatsApp as a supported messaging channel and added details on multi-platform deployment and session synchronization features.
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
koverholt
left a comment
koverholt
left a comment
There was a problem hiding this comment.
Thanks for the integration updates and the PR! Before this can go in, the page needs to be substantially trimmed back down.
The main thing to keep in mind is that this integration page is meant to be short, concise, and get a user started quickly with a single representative example. It should not attempt to fully document the connector. All of the deeper functionality belongs in the project's own repo, README, and docs, which are the source of truth and won't drift out of date the way a duplicate here will.
This PR re-introduces a lot of the material we intentionally pared down when the page first landed. I've left inline comments, but the recurring theme is: keep this page as a concise and low-maintenance quickstart, drop the sections that duplicate the README, and let the repo documentation explain the further details and config.
To this effect, I've suggest a few sections to remove and just keep as brief mentions in the intro, with a statement that users can go to the project repo to find out more about all supported messaging platforms, multi-channel support, multi-agent support, and sub-agent setups.
We appreciate the contribution, and we're happy to re-review once these are addressed. Thanks!
| --- | ||
| catalog_title: ADK Connector | ||
| catalog_description: Expose ADK agents as chatbots on popular messaging channels with cross-device session sync | ||
| catalog_description: Expose ADK agents as chatbots on Telegram, Discord, WhatsApp, and more with cross-device session sync |
There was a problem hiding this comment.
Let's revert this to the original description. The card description needs to stay short, and enumerating each messaging app means we have to update this card on every connector release. The generic phrasing avoids that maintenance burden.
| catalog_tags: ["connectors"] | ||
| --- | ||
|
|
||
| # ADK Connector |
There was a problem hiding this comment.
The H1 should follow the convention used by every other integration page. Please use: "ADK Connector messaging integration for ADK", "ADK Connector messaging toolkit for ADK", or similar.
| messaging channels such as Telegram, Discord, and WhatsApp. A Slack connector | ||
| is planned. See the project repository for the current list of supported |
There was a problem hiding this comment.
Remove "A Slack connector is planned", we don't need to track roadmap/planned work for third-party projects on this page; the repo is the source of truth for that.
| the current list of supported channels. | ||
| messaging channels such as Telegram, Discord, and WhatsApp. A Slack connector | ||
| is planned. See the project repository for the current list of supported | ||
| channels. |
There was a problem hiding this comment.
Please add a link to the project repository so users can go there to see the currently supported list of messaging platforms.
| ## Key features | ||
|
|
||
| - **Minimal wrapper**: Deploy any `google-adk` agent (Python or | ||
| JavaScript/TypeScript) to messaging channels with virtually zero code changes. | ||
| - **Auto tunnel and webhook server**: Set `tunnel=True` on the Telegram connector | ||
| to automatically spin up a local HTTP server and a Cloudflare Tunnel with zero | ||
| configuration, an automatic precompiled binary downloader, and port-collision | ||
| avoidance. | ||
| - **Cross-device session sync**: Chat on Telegram, Discord, or WhatsApp, then | ||
| inspect and continue the exact same conversation inside the ADK Web UI | ||
| (`adk web`). | ||
| - **Automatic database engine setup**: Transparently spins up an asynchronous | ||
| SQLite backend to record session states, events, and tool invocations. | ||
| - **Local persistent mapping**: Uses a secure, local JSON mapping engine so | ||
| restarting the bot never breaks session IDs or active chats. | ||
| - **Unified multi-platform deployment**: Run one agent across Telegram, Discord, | ||
| and WhatsApp concurrently with `ConnectorManager`. | ||
| - **Multi-agent support**: Built-in double-import safety and automatic | ||
| resolution of prompt context variables across parent and sub-agents. |
There was a problem hiding this comment.
Please remove this section. No other integration page has a "Key features" section, and this largely duplicates "Use cases". The upstream README and project docs are the right place for a full feature list.
You can move or combine items from this section into the "Use Cases" section, but please keep the Use Cases section concise with 3-5 bullet points total.
| ## Telegram webhook tunneling | ||
|
|
||
| By default, the Telegram connector uses long-polling to retrieve messages. For | ||
| faster response times, lower latency, and production parity, you can switch to | ||
| webhooks using the auto-tunnel feature: | ||
|
|
||
| ```python | ||
| connector = TelegramConnector( | ||
| token=token, | ||
| agent=assistant, | ||
| tunnel=True, # Spins up HTTP server and Cloudflare tunnel automatically | ||
| webhook_secret="optional-webhook-secret-token" # Verify Telegram payloads securely | ||
| ) | ||
| ``` | ||
|
|
||
| When `tunnel=True`, the connector: | ||
|
|
||
| 1. Downloads the `cloudflared` binary automatically if it is not on your PATH | ||
| and caches it in `~/.adk/bin/`. | ||
| 2. Starts a background HTTP web server (built on `aiohttp`) on your machine. | ||
| 3. Finds the next free port if the default port (`8000`) is already occupied. | ||
| 4. Spawns a Cloudflare tunnel (using `trycloudflare.com`) to expose your local | ||
| port securely to the internet. | ||
| 5. Registers the dynamic HTTPS endpoint with Telegram. | ||
| 6. Deletes the webhook registration and shuts down tunnel processes cleanly when | ||
| the bot stops. |
There was a problem hiding this comment.
Let's remove this section and replace it with a short note nested inside the Telegram tab so it only appears when Telegram is selected, e.g.: "The Telegram connector also supports automatic webhook tunneling via tunnel=True. See the project docs for details." The step-by-step internals are implementation details that should live upstream, not on this integration page.
| ## Multi-agent and sub-agent support | ||
|
|
||
| `adk-connector` supports complex agents that delegate tasks to sub-agents (for | ||
| example, using `sub_agents=[...]` or `tools=[AgentTool(agent=...)]`). | ||
|
|
||
| - **No extra launcher files**: Integrate `adk-connector` directly inside your | ||
| main `agent.py` file under `if __name__ == "__main__":`. You do not need a | ||
| separate script such as `run_telegram.py`. | ||
| - **Auto-resolution of missing state variables**: Sub-agents often expect prompt | ||
| context variables (for example, `{seminal_paper}`) populated by parent outputs | ||
| from previous turns. `adk-connector` scans parent and sub-agent instructions | ||
| for curly-brace placeholders and pre-populates them dynamically before | ||
| executing the runner, preventing `KeyError: 'Context variable not found'` | ||
| crashes. | ||
| - **Double-import safety**: Running multi-agent code as a script | ||
| (`python -m package.module`) can trigger Python double-import cycles. When an | ||
| ADK agent is instantiated twice in this cycle, Pydantic throws a validation | ||
| error because sub-agents are assigned a parent twice. `adk-connector` | ||
| overrides ADK parent-validation checks to allow safe duplicate parent | ||
| resolution under import cycles. |
There was a problem hiding this comment.
I'd recommend removing this section. It's upstream implementation detail (Pydantic double-import behavior, KeyError internals, monkeypatching parent validation) that's really about how the library works internally, not how a user gets started.
Instead you can add a sentence to the intro: "This integration also supports running a single agent across multiple channels at once, as well as multi-agent and sub-agent setups."
| ## Multi-platform deployment | ||
|
|
||
| To deploy one agent across multiple platforms simultaneously (for example, | ||
| Telegram, Discord, and WhatsApp), use `ConnectorManager` as a central hub. | ||
| Initialize platform connectors without an `agent` argument, pass them into | ||
| `ConnectorManager`, and run them together with `start_sync()`: | ||
|
|
||
| ```python | ||
| import os | ||
| from dotenv import load_dotenv | ||
| from google.adk.agents.llm_agent import Agent | ||
| from adk_connectors import ConnectorManager | ||
| from adk_connectors.telegram import TelegramConnector | ||
| from adk_connectors.discord import DiscordConnector | ||
| from adk_connectors.whatsapp import WhatsAppConnector | ||
|
|
||
| load_dotenv() | ||
|
|
||
| assistant = Agent( | ||
| model='gemini-flash-latest', | ||
| name='my_assistant', | ||
| instruction='You are a helpful assistant.' | ||
| ) | ||
|
|
||
| if __name__ == "__main__": | ||
| platforms = [] | ||
|
|
||
| telegram_token = os.getenv("TELEGRAM_BOT_TOKEN") | ||
| if telegram_token: | ||
| platforms.append( | ||
| TelegramConnector(token=telegram_token, streaming=True, tunnel=True) | ||
| ) | ||
|
|
||
| discord_token = os.getenv("DISCORD_BOT_TOKEN") | ||
| if discord_token: | ||
| platforms.append( | ||
| DiscordConnector(token=discord_token, streaming=True) | ||
| ) | ||
|
|
||
| platforms.append( | ||
| WhatsAppConnector(port=3001) | ||
| ) | ||
|
|
||
| manager = ConnectorManager( | ||
| agent=assistant, | ||
| platforms=platforms, | ||
| session_management_across_device=True, | ||
| dev_user_id=os.getenv("TELEGRAM_USER_ID") | ||
| ) | ||
|
|
||
| manager.start_sync() | ||
| ``` |
There was a problem hiding this comment.
This is a large code block lifted from the README. We don't need to fully document this on the integration page.
Instead you can add a sentence to the intro: "This integration also supports running a single agent across multiple channels at once, as well as multi-agent and sub-agent setups."
| ## Supported channels | ||
|
|
||
| | Channel | Status | | ||
| | ------- | ------ | | ||
| | Telegram | Available | | ||
| | Discord | Available | | ||
| | WhatsApp | Available | | ||
| | Slack | Planned | |
There was a problem hiding this comment.
Please remove this table. The supported channels are already covered by the intro, and we deliberately point users to the repo ("See the project repository for the current list of supported channels") so we don't maintain a duplicate list here that drifts out of date.
| - [ADK Connector GitHub Repository](https://github.com/Harshk133/adk-connector) | ||
| - [ADK Connector Python Package (PyPI)](https://pypi.org/project/adk-connector/) | ||
| - [ADK Connector JS/TS Package (NPM)](https://www.npmjs.com/package/adk-connector-js) | ||
| - [blog-writer setup demo](https://github.com/google/adk-samples/tree/main/python/agents/blog-writer) |
There was a problem hiding this comment.
This links to the official adk-samples blog-writer sample agent, which doesn't reference this connector, so it isn't a relevant resource. I'd replace the link with a link to the examples in your own repo, https://github.com/Harshk133/adk-connector/tree/main/examples/.
2 participants
Updated the ADK Connector documentation to include WhatsApp as a supported messaging channel and added details on multi-platform deployment and session synchronization features.