tai42-tools-whatsapp
WhatsApp provisioning tools for the TAI ecosystem — manifest-loaded Meta Graph tools that register a message template, list the business account's message templates, delete a template by name, and subscribe the app to a WhatsApp Business Account's webhooks.
All Graph traffic is direct REST through tai42-kit's curl client (no vendor
SDK); the Graph host and pinned API version ride the settings below. The package
registers its tools through the tai42_app handle from tai42_contract.app and
never imports the skeleton.
The TAI ecosystem
TAI is an open-source runtime for MCP tools, agents, and workflows. A tool is a callable the host loads from a plugin manifest; this package supplies the WhatsApp provisioning tools. The ecosystem is open-ended, so this repo is these tools' own full doc home, and the documentation site covers the platform-level story:
- Tools concept: https://tai42.ai/concepts/tools
- Build a tool (author guide): https://tai42.ai/guides/authors/tool
- Ecosystem catalog: https://tai42.ai/reference/catalog
The current release line tracks the 7.x contract (tai42-contract>=7,<8).
Install
Requires Python 3.13+. Install from PyPI into the environment that runs the server:
uv add tai42-tools-whatsapp
Or from source — clone this repo and add it as an editable dependency; the
tai42-* dependencies resolve in-tree from the workspace.
git clone https://github.com/tai42ai/tai42 # next to your app checkout
cd /path/to/your/app
uv add --editable ../tai42/plugins/tools-whatsapp
Catalog
| Tool | Description |
|---|---|
register_whatsapp_template |
Registers a message template on the account and returns Graph's id and review status. |
list_whatsapp_templates |
Lists every message template on the account, following Graph's paging cursors to exhaustion. |
delete_whatsapp_template |
Deletes a message template by name (percent-encoded into the query) and returns Graph's response. |
subscribe_whatsapp_app |
Subscribes the app to the account's webhooks, optionally overriding the callback URI and verify token. |
Registering templates
register_whatsapp_template takes name, language, category, and a
Graph-shaped components list (all required and non-empty). components is
passed through unchanged — Graph validates its shape and rejects a malformed one
with its own error, which propagates. The tool returns Graph's response (the new
template's id and review status).
list_whatsapp_templates returns the concatenated data across every page,
following Graph's paging.next cursor until Graph stops sending one, so a long
template catalog is never silently truncated. delete_whatsapp_template takes a
single name, percent-encoded into the delete query.
Subscribing webhooks
subscribe_whatsapp_app subscribes the app to the account's webhooks. With both
callback_uri and verify_token supplied it overrides the app's configured
webhook with Meta's override_callback_uri + verify_token pair; with neither
it subscribes to the app's configured webhook. Supplying exactly one of the two
raises.
Configuration
| Setting | Env var | Default | Purpose |
|---|---|---|---|
| Access token | CHANNEL_WHATSAPP_ACCESS_TOKEN |
— | Graph API bearer token. Required. |
| Business account | CHANNEL_WHATSAPP_WABA_ID |
— | WhatsApp Business Account id the endpoints hang under. Required. |
| API base | CHANNEL_WHATSAPP_API_BASE_URL |
https://graph.facebook.com/v23.0 |
Graph API origin with a pinned version. |
| Request timeout | CHANNEL_WHATSAPP_HTTP_TIMEOUT_SECONDS |
30 |
Per-request HTTP timeout. |
The token and WABA id share the CHANNEL_WHATSAPP_ env group with the rest of
the WhatsApp deployment. Secrets live only in the environment; the access token
is held as a secret and never appears in a log or a raised error. A missing or
empty required credential raises loudly (fails closed), and every non-2xx from
Graph raises with Graph's status and body — never a silent default.
Development
uv venv --python 3.13
uv pip install --no-sources --extra dev --editable .
uv run --no-sync pytest --cov --cov-report=term-missing
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync pyright
License
Apache-2.0. See LICENSE and NOTICE.
1 maintainer
Metadata
1 maintainer
Release files for tai42-tools-whatsapp 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tai42_tools_whatsapp-1.1.0.tar.gz | 16.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai42_tools_whatsapp-1.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 34.9 kB
Release files / tai42_tools_whatsapp-1.1.0.tar.gz
| Download URL | tai42_tools_whatsapp-1.1.0.tar.gz |
|---|---|
| Size | 16.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4da6e3bf2c4c2b1264cf05a734f43ff955dac7d9e54f453e0c6acc7b1f194e5
|
|
BLAKE2b-256 checksum How to use checksums |
b812774ff2e5287d605f254cd88b241e51fe512678301708882da6866300c770
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / tai42_tools_whatsapp-1.1.0-py3-none-any.whl
| Download URL | tai42_tools_whatsapp-1.1.0-py3-none-any.whl |
|---|---|
| Size | 18.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
92b67b2b1460f89ee72209a17ee4e9a72268000f7cf826f8d531fc86feba1241
|
|
BLAKE2b-256 checksum How to use checksums |
d736e4a2e56a0817bbdd017608cf2f468565fe392c7431a69783f0bbfb54123b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
