Skip to main content

WIIL Python SDK

Ship AI-powered business features without building telecom, catalog infrastructure, or integration plumbing.

Python License: MIT


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

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_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


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)

Source distribution for wiil-python 0.0.19
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)

Table of built distributions (wheels) for wiil-python 0.0.19
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page