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
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 2.0.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 | Provenance | |
|---|---|---|---|---|
| tai42_tools_whatsapp-2.0.0.tar.gz | 16.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai42_tools_whatsapp-2.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 35.2 kB
Release files / tai42_tools_whatsapp-2.0.0.tar.gz
| Download URL | tai42_tools_whatsapp-2.0.0.tar.gz |
|---|---|
| Size | 16.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c26b0728b13a821ddc1912001baa716d9355e81444b3cf2df444e35d68af4022
|
|
BLAKE2b-256 checksum How to use checksums |
1648a947a24fbff15efe1aaa22b697c51f4452e7d4b2f33f231c617909fa0279
|
| 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-2.0.0-py3-none-any.whl
| Download URL | tai42_tools_whatsapp-2.0.0-py3-none-any.whl |
|---|---|
| Size | 18.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1691accb892437998fb4c0ceabb1ab30b08346f9a3ce95adc352ef915256349a
|
|
BLAKE2b-256 checksum How to use checksums |
2906374bf6a4e18f4431356fa0fd8be28e0fb4f5be237b256feea3c784df76b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for tai42-tools-whatsapp 2.0.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
