WIIL Python SDK
Ship AI-powered business features without building telecom, catalog infrastructure, or integration plumbing.
What You Can Ship
This SDK gives you APIs to build:
- Catalog-aware AI agents - Agents grounded in real business data such as menus, products, services, reservations, and properties
- Multi-channel conversations - Web, phone, SMS, and email workflows through unified APIs
- Transaction workflows - Appointments, reservations, orders, inquiries, and outbound follow-ups
- Outbound communications - Automated calls, emails, and SMS without provider setup
What you skip building:
- Telephony integration, SMS gateways, SMTP servers
- Voice pipeline infrastructure for STT, LLM, and TTS workflows
- Catalog schema design and multi-location logic
- Retry logic, queue management, and delivery tracking
- Channel-specific protocols and failure handling
You write the business logic. The SDK handles the infrastructure.
Installation
pip install wiil-python
For isolated projects:
python -m venv .venv
source .venv/bin/activate
pip install wiil-python
On Windows PowerShell:
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install wiil-python
Quick Start
import os
from wiil import WiilClient
client = WiilClient(api_key=os.environ["WIIL_API_KEY"])
Deploy an AI Agent
from wiil.models.service_mgt.dynamic_setup import (
DynamicPhoneAgentSetup,
DynamicWebAgentSetup,
)
from wiil.types import BusinessSupportServices
# Phone agent with live number
phone = client.dynamic_phone_agent.create(
DynamicPhoneAgentSetup(
assistant_name="Sarah",
capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
)
)
print("Phone number:", phone.phone_number)
# Web agent with widget snippets
web = client.dynamic_web_agent.create(
DynamicWebAgentSetup(
assistant_name="Emma",
website_url="https://example.com",
capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
)
)
print("Widget snippets:", web.integration_snippets)
Send Notifications
import time
from wiil.models.conversation import (
CreateCallRequest,
CreateEmailRequest,
CreateSmsRequest,
EmailRecipient,
)
from wiil.types import ScheduleType
# Email
client.outbound_emails.create(
CreateEmailRequest(
to=[EmailRecipient(email="customer@example.com")],
template_id="order_confirmation",
subject="Order confirmed",
body_html="<p>Your order {{orderNumber}} is confirmed.</p>",
body_text="Your order {{orderNumber}} is confirmed.",
variables={"orderNumber": "ORD-123"},
)
)
# SMS
client.outbound_sms.create(
CreateSmsRequest(
to="+14155551234",
from_number="+14155555678",
body="Your appointment is confirmed for tomorrow at 2 PM.",
)
)
# Voice call
client.outbound_calls.create(
CreateCallRequest(
to="+14155551234",
from_number="+14155555678",
agent_configuration_id="reminder_agent",
schedule_type=ScheduleType.SCHEDULED,
scheduled_at=int(time.time() * 1000) + 2 * 60 * 60 * 1000,
)
)
Manage Business Catalogs
from wiil.models.business_mgt import (
CreateBusinessMenuItem,
CreateBusinessMenuItemVariant,
CreateBusinessProduct,
CreateBusinessProductVariant,
CreateBusinessService,
)
# Services
service = client.business_services.create(
CreateBusinessService(
name="Hair Styling",
duration=60,
base_price=75.00,
)
)
# Menu items with variants
menu_item = client.menus.create_item(
CreateBusinessMenuItem(
name="Cheeseburger",
category_id="cat_main",
price=12.99,
variants=[
CreateBusinessMenuItemVariant(
name="Regular",
price=12.99,
is_default=True,
is_active=True,
is_available=True,
)
],
)
)
# Products with variants
product = client.products.create(
CreateBusinessProduct(
name="Wireless Mouse",
category_id="cat_electronics",
price=29.99,
is_alcoholic=False,
variants=[
CreateBusinessProductVariant(
axis_values={},
price=29.99,
is_default=True,
is_active=True,
)
],
)
)
Book Transactions Through AI Workflows
from wiil.models.business_mgt import CreateServiceAppointment, CreateTableReservation
appointment = client.service_appointments.create(
CreateServiceAppointment(
business_service_id=service.id,
customer_id="cust_123",
start_time=int(time.time() * 1000) + 24 * 60 * 60 * 1000,
duration=60,
)
)
reservation = client.table_reservations.create(
CreateTableReservation(
resource_id="table_5",
customer_id="cust_123",
floor_plan_id="floor_main",
persons_number=4,
time=int(time.time() * 1000) + 2 * 60 * 60 * 1000,
duration=90,
)
)
Examples & Guides
Comprehensive guides are in the examples/ directory.
Getting Started
| Guide | What You Build |
|---|---|
| Dynamic Agent Setup | Deploy phone/web agents in one API call |
| Fundamental Configuration | Fine-grained multi-step agent setup |
Outbound Communications
| Guide | What You Build |
|---|---|
| Outbound Communications | Full notification system across calls, email, and SMS |
| Messaging Quick Start | Send your first notification in minutes |
Business Services
| Guide | What You Build |
|---|---|
| Services & Appointments | Bookable services and appointment scheduling |
| Menus & Orders | Restaurant menus and food ordering |
| Products & Orders | Product catalogs and retail orders |
| Reservations | Tables, rooms, rentals, and bookings |
| Property Management | Listings, inquiries, and lead tracking |
Channels
| Guide | What You Build |
|---|---|
| Web Channels | Chat widget integration |
| Voice Channels | Phone call handling |
| SMS Channels | Text messaging |
SDK Features
- Type-Safe - Python type hints with Pydantic models
- Validated - Runtime validation using Pydantic
- Production-Grade - Robust error handling and configurable timeouts
- Modern - Synchronous and asynchronous clients
- Comprehensive - Account, service management, business management, conversation, and outbound resources
Available Resources
Dynamic Agent Setup
client.dynamic_phone_agent
client.dynamic_web_agent
client.dynamic_agent_status
Outbound APIs
client.outbound_templates
client.outbound_calls
client.outbound_emails
client.outbound_sms
Service Configuration
client.agent_configs
client.instruction_configs
client.deployment_configs
client.deployment_channels
client.provisioning_configs
client.support_models
client.telephony_provider
client.conversation_configs
client.knowledge_sources
Business Management
client.business_services
client.customers
client.menus
client.menu_item_variants
client.modifiers
client.products
client.product_variants
client.product_sets
client.service_appointments
client.table_reservations
client.room_reservations
client.rental_reservations
client.menu_orders
client.product_orders
client.reservation_resources
client.floor_plans
client.property_config
client.property_inquiry
Error Handling
from wiil.errors import WiilAPIError, WiilNetworkError, WiilValidationError
try:
result = client.business_services.create(
CreateBusinessService(name="Consultation", duration=30, base_price=50)
)
except WiilValidationError as exc:
print("Invalid input:", exc.details)
except WiilAPIError as exc:
print(f"API error {exc.status_code}:", exc.message)
print("Code:", exc.code)
except WiilNetworkError:
print("Network error. Retry with backoff.")
Async Support
import asyncio
import os
from wiil import AsyncWiilClient
async def main() -> None:
async with AsyncWiilClient(api_key=os.environ["WIIL_API_KEY"]) as client:
organization = await client.organizations.get()
print("Organization:", organization.company_name)
asyncio.run(main())
Configuration
from wiil import WiilClient
client = WiilClient(
api_key="your-api-key",
base_url="https://api.wiil.io/v1",
timeout=60,
)
Security
Server-side only. Never expose your API key in client-side code.
import os
from wiil import WiilClient
# Good: environment variable
client = WiilClient(api_key=os.environ["WIIL_API_KEY"])
# Bad: hardcoded key
client = WiilClient(api_key="sk_live_...")
Requirements
- Python 3.8 or higher
- Pydantic
- requests/httpx, depending on sync or async usage
Development
pip install -e ".[dev]"
pytest
pytest --cov=wiil --cov-report=html
black wiil tests
ruff check wiil tests
mypy wiil
Support
- Documentation: https://docs.wiil.io
- API Reference: https://docs.wiil.io/developer/api-reference
- Issues: GitHub Issues
- Email: dev-support@wiil.io
License
MIT (c) WIIL
Built with care by the WIIL team
Metadata
Release files for wiil-python 0.0.19
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 | Actions |
|---|---|---|---|---|
| wiil_python-0.0.19.tar.gz | 192.6 kB | Without provenance | Details for wiil_python-0.0.19.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wiil_python-0.0.19-py3-none-any.whl | Python 3 | none | any | Details for wiil_python-0.0.19-py3-none-any.whl |
Total release size: 509.1 kB
Release files / wiil_python-0.0.19.tar.gz
| Download URL | wiil_python-0.0.19.tar.gz |
|---|---|
| Size | 192.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6c38a732e161c6690902bf55ecf2a32c2c5c3453406cb1a1f9888688add763d6
|
|
BLAKE2b-256 checksum How to use checksums |
f1f7f18841ae073dbb3f7dc0da00a635ca91bf8f1f75fd2af35dd6df4b7844c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / wiil_python-0.0.19-py3-none-any.whl
| Download URL | wiil_python-0.0.19-py3-none-any.whl |
|---|---|
| Size | 316.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ec58c9c63c74aac6ce1c080a1d02d6bb9415f0cc786278cf8921597c114ce16
|
|
BLAKE2b-256 checksum How to use checksums |
354edb1932b13a72a720f3fdf7753e32388c01bd0842b03525c9e34441d45295
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for wiil-python 0.0.19
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.