WIIL JavaScript 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 (menus, products, services, properties)
• Multi-channel conversations — Web, phone, SMS, email through unified APIs
• Transaction workflows — Appointments, reservations, orders, inquiries
• Outbound communications — Automated calls, emails, SMS without provider setup

What you skip building:

• Telephony integration, SMS gateways, SMTP servers
• Voice pipeline (STT → LLM → TTS)
• Catalog schema design and multi-location logic
• Retry logic, queue management, delivery tracking
• Channel-specific protocols and failure handling

You write the business logic. The SDK handles the infrastructure.

Installation

npm install wiil-js

Quick Start

import { WiilClient } from 'wiil-js';

const client = new WiilClient({
  apiKey: process.env.WIIL_API_KEY!
});

Deploy an AI Agent (One Call)

import { BusinessSupportServices } from 'wiil-core-js';

// Phone agent with live number
const phone = await client.dynamicPhoneAgent.create({
  assistantName: 'Sarah',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});
console.log('Phone number:', phone.phoneNumber);

// Web agent with widget
const web = await client.dynamicWebAgent.create({
  assistantName: 'Emma',
  websiteUrl: 'https://example.com',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});
console.log('Widget snippets:', web.integrationSnippets);

Send Notifications (No Provider Setup)

// Email
await client.outboundEmails.create({
  to: [{ email: '[email protected]' }],
  templateId: 'order_confirmation',
  templateVariables: { orderNumber: 'ORD-123', total: '99.99' },
});

// SMS
await client.outboundSms.create({
  to: '+14155551234',
  from: '+14155555678',
  body: 'Your appointment is confirmed for tomorrow at 2 PM.',
});

// Voice call
await client.outboundCalls.create({
  to: '+14155551234',
  from: '+14155555678',
  agentConfigurationId: 'reminder_agent',
  scheduleType: 'scheduled',
  scheduledAt: Date.now() + (2 * 60 * 60 * 1000),
});

Manage Business Catalogs

// Services
const service = await client.services.create({
  name: 'Hair Styling',
  duration: 60,
  basePrice: 75.00,
});

// Menu items (with variants)
const menuItem = await client.menuItems.create({
  name: 'Cheeseburger',
  categoryId: 'cat_main',
  variants: [{ name: 'Regular', price: 12.99, isDefault: true, isActive: true, isAvailable: true }],
});

// Products (with variants)
const product = await client.products.create({
  name: 'Wireless Mouse',
  categoryId: 'cat_electronics',
  isAlcoholic: false,
  variants: [{ axisValues: {}, price: 29.99, isDefault: true, isActive: true }],
});

Book Transactions Through AI

// Appointment
const appointment = await client.serviceAppointments.create({
  businessServiceId: service.id,
  customerId: 'cust_123',
  startsAt: Date.now() + (24 * 60 * 60 * 1000),
  duration: 60,
});

// Table reservation
const reservation = await client.tableReservations.create({
  floorPlanId: 'floor_main',
  customerId: 'cust_123',
  time: Date.now() + (2 * 60 * 60 * 1000),
  duration: 90,
  personsNumber: 4,
});

Examples & Guides

Comprehensive guides are in the examples/ directory:

Getting Started

| Guide | What You'll 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'll Build | | ----- | ----------------- | | Outbound Communications | Full notification system — calls, email, SMS | | Messaging Quick Start | Send your first notification in minutes |

Business Services

| Guide | What You'll Build | | ----- | ----------------- | | Services & Appointments | Bookable services, appointment scheduling | | Menus & Orders | Restaurant menus, food ordering | | Products & Orders | Product catalogs, retail orders | | Reservations | Tables, rooms, rentals | | Property Management | Listings, inquiries, lead tracking |

Channels

| Guide | What You'll Build | | ----- | ----------------- | | Web Channels | Chat widget integration | | Voice Channels | Phone call handling | | SMS Channels | Text messaging |

See all examples →

SDK Features

• Type-Safe — Full TypeScript with comprehensive type definitions
• Validated — Runtime validation using Zod schemas
• Production-Grade — Robust error handling, configurable timeouts
• Modern — ES2023, async/await, Promise-based

Available Resources

Dynamic Agent Setup

client.dynamicPhoneAgent  // Single-call phone agent deployment
client.dynamicWebAgent    // Single-call web agent deployment

Outbound APIs

client.outboundTemplates  // Email/SMS templates
client.outboundCalls      // Automated voice calls
client.outboundEmails     // Transactional emails
client.outboundSms        // SMS messages

Service Configuration

client.agentConfigs         // Agent configurations
client.instructionConfigs   // Agent behavior/prompts
client.deploymentConfigs    // Deployment configurations
client.deploymentChannels   // Communication channels
client.provisioningConfigs  // STT/TTS chain configs
client.supportModels        // AI model registry
client.telephonyProvider    // Phone number provisioning

Business Management

client.services             // Business services
client.customers            // Customer management
client.menuCategories       // Menu categories
client.menuItems            // Menu items with variants
client.products             // Products with variants
client.serviceAppointments  // Appointment bookings
client.tableReservations    // Table reservations
client.roomReservations     // Room reservations
client.rentalReservations   // Rental reservations
client.menuOrders           // Menu orders
client.productOrders        // Product orders
client.floorPlans           // Floor plans and tables
client.propertyConfig       // Property listings
client.propertyInquiries    // Property inquiries

Error Handling

import {
  WiilAPIError,
  WiilValidationError,
  WiilNetworkError
} from 'wiil-js';

try {
  const result = await client.services.create({ ... });
} catch (error) {
  if (error instanceof WiilValidationError) {
    console.error('Invalid input:', error.details);
  } else if (error instanceof WiilAPIError) {
    console.error(`API Error ${error.statusCode}:`, error.message);
  } else if (error instanceof WiilNetworkError) {
    console.error('Network error — retry the request');
  }
}

Configuration

const client = new WiilClient({
  apiKey: process.env.WIIL_API_KEY!,
  baseUrl: 'https://api.wiil.io/v1',  // Optional
  timeout: 60000                       // Optional, ms
});

Security

Server-side only. Never expose your API key in client-side code.

// ✅ Good — environment variable
const client = new WiilClient({
  apiKey: process.env.WIIL_API_KEY!
});

// ❌ Bad — hardcoded key
const client = new WiilClient({
  apiKey: 'sk_live_...'  // Never do this
});

Requirements

• Node.js 16.x or higher
• TypeScript 5.x (for TypeScript projects)

Development

npm run build          # Build
npm test               # Run tests
npm run test:coverage  # Tests with coverage

Support

• Documentation: https://docs.wiil.io
• API Reference: https://docs.wiil.io/developer/api-reference
• Issues: GitHub Issues
• Email: [email protected]

License

MIT © WIIL

Built with care by the WIIL team