Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

WIIL Python SDK Examples

This directory contains examples and guides for building AI-powered business workflows with the WIIL Python SDK.

Getting Started

Prerequisites

  1. WIIL Platform Account

  2. API Key

    • Navigate to Settings -> API Keys in the WIIL Console
    • Generate and securely store your API key

  3. Python Environment

    • Python 3.8 or higher
    • A virtual environment is recommended

Installation

pip install wiil-python

Environment Setup

Create a .env file or export the variable in your shell:

WIIL_API_KEY=your-api-key-here

Never commit API keys or .env files to version control.

Quick Start Guides

Dynamic Agent Setup

File: dynamic-agent-setup-guide.md

The fastest path to deploy phone or web agents. Use this when you want the platform to provision the required agent, instruction, deployment, and channel pieces for you.

import os

from wiil import WiilClient
from wiil.models.service_mgt.dynamic_setup import DynamicPhoneAgentSetup
from wiil.types import BusinessSupportServices

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

result = client.dynamic_phone_agent.create(
    DynamicPhoneAgentSetup(
        assistant_name="Sarah",
        capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
    )
)

print("Phone number:", result.phone_number)

Read the Dynamic Setup Guide

Fundamental Configuration Setup

File: fundamental-configuration-setup.md

Use the fundamental setup guide when you need fine-grained control over instructions, support models, agent configurations, deployment channels, and deployment configurations.

Setup steps:

  1. Initialize the client and verify organization access
  2. Create or select a project
  3. Create an instruction configuration
  4. Select a support model
  5. Create an agent configuration
  6. Create a deployment channel
  7. Create a deployment configuration
  8. Deploy and verify

Read the Fundamental Configuration Guide

Outbound Communications

Full Guide

File: outbound-communications-guide.md

Build notification workflows across SMS, email, and AI-powered outbound calls without managing provider integrations directly.

Messaging Quick Start

File: messaging-guide.md

Send your first SMS, email, and outbound call:

from wiil.models.conversation import CreateSmsRequest

sms = client.outbound_sms.create(
    CreateSmsRequest(
        to="+12125551234",
        from_number="+12125559999",
        body="Your appointment is confirmed for tomorrow at 3 PM.",
    )
)

Read the Messaging Guide

Business Service Guides

Directory: business-services/

Guide What You Build
Services & Appointments Bookable services and appointment scheduling
Menus & Orders Restaurant menus, item variants, modifiers, and orders
Products & Orders Product catalogs, variants, pricing, and product orders
Reservations Reservable tables, rooms, rentals, and booking flows
Property Management Property listings, inquiries, and lead tracking

Channels

Directory: channels/

Guide What You Build
Channel Overview Channel concepts and setup flow
Understanding Channels Channel types and architecture
Web Channels Web chat widget deployment
Voice Channels Phone call handling
SMS Channels Text messaging channels
Phone Purchase Phone number provisioning
Troubleshooting Common channel issues

Service Management Guides

Directory: service-mgt/

Guide What You Configure
Agent Configs Agent identity, services, and model selection
Instruction Configs Agent role, instructions, and guardrails
Deployment Channels Web, voice, SMS, and email channels
Deployment Configs Live deployment bindings
Provisioning Configs STT/TTS voice chains
Knowledge Sources Agent knowledge bases
Support Models Available AI, STT, and TTS models
Telephony Provider Phone number/provider operations
Translation Sessions Real-time translation sessions

Configuration Flow

Organization
  -> Project
    -> Instruction Configuration
    -> Support Model
    -> Agent Configuration
    -> Deployment Channel
    -> Deployment Configuration
      -> Live Agent

Dynamic setup creates much of this chain for you. Fundamental setup exposes each step directly.

Error Handling

from wiil.errors import WiilAPIError, WiilNetworkError, WiilValidationError

try:
    result = client.deployment_configs.create(payload)
except WiilValidationError as exc:
    print("Invalid input:", exc.details)
except WiilAPIError as exc:
    print(f"API error {exc.status_code}:", exc.message)
except WiilNetworkError:
    print("Network error. Check connectivity and retry.")

Security

The WIIL Python SDK is intended for server-side use. Never expose your API key in browser or mobile client code.

import os

from wiil import WiilClient

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

Support

Start with Dynamic Agent Setup for the quickest deployment path, or use Fundamental Configuration when you need full control.