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

importosfromwiilimportWiilClientclient=WiilClient(api_key=os.environ["WIIL_API_KEY"])

Deploy an AI Agent

fromwiil.models.service_mgt.dynamic_setupimport (
DynamicPhoneAgentSetup,
DynamicWebAgentSetup,
)
fromwiil.typesimportBusinessSupportServices# Phone agent with live numberphone=client.dynamic_phone_agent.create(
DynamicPhoneAgentSetup(
assistant_name="Sarah",
capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
)
)
print("Phone number:", phone.phone_number)
# Web agent with widget snippetsweb=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

importtimefromwiil.models.conversationimport (
CreateCallRequest,
CreateEmailRequest,
CreateSmsRequest,
EmailRecipient,
)
fromwiil.typesimportScheduleType# Emailclient.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"},
)
)
# SMSclient.outbound_sms.create(
CreateSmsRequest(
to="+14155551234",
from_number="+14155555678",
body="Your appointment is confirmed for tomorrow at 2 PM.",
)
)
# Voice callclient.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

fromwiil.models.business_mgtimport (
CreateBusinessMenuItem,
CreateBusinessMenuItemVariant,
CreateBusinessProduct,
CreateBusinessProductVariant,
CreateBusinessService,
)
# Servicesservice=client.business_services.create(
CreateBusinessService(
name="Hair Styling",
duration=60,
base_price=75.00,
)
)
# Menu items with variantsmenu_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 variantsproduct=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

fromwiil.models.business_mgtimportCreateServiceAppointment, CreateTableReservationappointment=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

See all examples

---

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_agentclient.dynamic_web_agentclient.dynamic_agent_status

Outbound APIs

client.outbound_templatesclient.outbound_callsclient.outbound_emailsclient.outbound_sms

Service Configuration

client.agent_configsclient.instruction_configsclient.deployment_configsclient.deployment_channelsclient.provisioning_configsclient.support_modelsclient.telephony_providerclient.conversation_configsclient.knowledge_sources

Business Management

client.business_servicesclient.customersclient.menusclient.menu_item_variantsclient.modifiersclient.productsclient.product_variantsclient.product_setsclient.service_appointmentsclient.table_reservationsclient.room_reservationsclient.rental_reservationsclient.menu_ordersclient.product_ordersclient.reservation_resourcesclient.floor_plansclient.property_configclient.property_inquiry

---

Error Handling

fromwiil.errorsimportWiilAPIError, WiilNetworkError, WiilValidationErrortry:
result=client.business_services.create(
CreateBusinessService(name="Consultation", duration=30, base_price=50)
)
exceptWiilValidationErrorasexc:
print("Invalid input:", exc.details)
exceptWiilAPIErrorasexc:
print(f"API error {exc.status_code}:", exc.message)
print("Code:", exc.code)
exceptWiilNetworkError:
print("Network error. Retry with backoff.")

---

Async Support

importasyncioimportosfromwiilimportAsyncWiilClientasyncdefmain() ->None:
asyncwithAsyncWiilClient(api_key=os.environ["WIIL_API_KEY"]) asclient:
organization=awaitclient.organizations.get()
print("Organization:", organization.company_name)
asyncio.run(main())

---

Configuration

fromwiilimportWiilClientclient=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.

importosfromwiilimportWiilClient# Good: environment variableclient=WiilClient(api_key=os.environ["WIIL_API_KEY"])
# Bad: hardcoded keyclient=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