tai42-tools-twilio
Twilio provisioning tools for the TAI ecosystem — manifest-loaded REST tools that list a Twilio account's incoming phone numbers, read a number's inbound-message webhook, and set a number's inbound-message webhook URL.
All Twilio traffic is direct REST through tai42-kit's curl client (no twilio
SDK); requests carry HTTP Basic auth (AccountSid:AuthToken). 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 Twilio number-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-twilio
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-twilio
Catalog
| Tool | Description |
|---|---|
list_twilio_numbers |
Lists the account's incoming phone numbers, following Twilio's paging to exhaustion, and returns each number's sid, phone_number, sms_url, and sms_method. |
get_twilio_number_webhook |
Reads one number's inbound-message webhook and returns its sid, phone_number, sms_url, and sms_method. |
set_twilio_number_webhook |
Sets a number's inbound-message webhook to an https URL and returns the updated sid, phone_number, and sms_url. |
Provisioning a number's inbound webhook
These tools configure the Twilio side of an inbound-message flow: they point a
number's "A message comes in" webhook at the platform's inbound endpoint so
Twilio POSTs each message there. list_twilio_numbers finds the number's sid,
get_twilio_number_webhook reads its current webhook, and
set_twilio_number_webhook writes a new one:
{ "sid": "PN...", "phone_number": "+15551234567", "sms_url": "https://app.example/api/channels/twilio/inbound" }
set_twilio_number_webhook requires an https URL and rejects an empty or
non-https value before any network call. Every Twilio non-2xx raises loudly with
its status and body — never remapped to success — and the Basic-auth header is
never echoed into the error.
Configuration
The tools read the same CHANNEL_TWILIO_ credentials as the deployment's Twilio
channel — one account SID, auth token, and REST base configure both.
| Setting | Env var | Default | Purpose |
|---|---|---|---|
| Account SID | CHANNEL_TWILIO_ACCOUNT_SID |
— | The Twilio account SID. Required. |
| Auth token | CHANNEL_TWILIO_AUTH_TOKEN |
— | The Twilio auth token. Required. |
| API base | CHANNEL_TWILIO_API_BASE_URL |
https://api.twilio.com/2010-04-01 |
Twilio REST origin (carries the API version prefix). |
| Request timeout | CHANNEL_TWILIO_HTTP_TIMEOUT_SECONDS |
30 |
Per-request timeout. |
Credentials live only in the environment. A missing or empty required credential raises loudly (fails closed), naming its env var and never the value.
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-twilio 1.0.14
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_twilio-1.0.14.tar.gz | 15.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai42_tools_twilio-1.0.14-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 32.6 kB
Release files / tai42_tools_twilio-1.0.14.tar.gz
| Download URL | tai42_tools_twilio-1.0.14.tar.gz |
|---|---|
| Size | 15.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
63a7627db00398fc09132689fdbfa194ec70f6c79269824ab99119897abb6406
|
|
BLAKE2b-256 checksum How to use checksums |
0ca211e45289484f35d753923bd3cbaf04342a0b22f6b9f00c8761142aaf688f
|
| 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_twilio-1.0.14-py3-none-any.whl
| Download URL | tai42_tools_twilio-1.0.14-py3-none-any.whl |
|---|---|
| Size | 17.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f797f1b0b10b0b55bff06ff8c1feb11cad52c37615f93f0658ec5b6bce6aebf
|
|
BLAKE2b-256 checksum How to use checksums |
4ae12f4c9402ffa2234a3256146f477797103c1375830b72e3df95c774fe3886
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
