Skip to main content

Schemas & Data Models

Comprehensive TypeScript/Zod schemas for type-safe integration with the WIIL Platform.

Overview​

The WIIL Platform provides strongly-typed schemas for all API entities, enabling:

  • Type Safety - Compile-time validation with TypeScript
  • Runtime Validation - Zod schema validation
  • IntelliSense - Full IDE autocomplete support
  • Documentation - Self-documenting code

Account​

ModelDescription
OrganizationCompany or business account
ProjectResource grouping within an organization
Business VerticalsIndustry classification values

Business models​

Business-domain models — services & appointments, menu, products, property, and reservations — are documented in depth elsewhere, so they are intentionally not duplicated here:

  • Catalog — narrative field references, enums, lifecycle diagrams, and TypeScript + Python examples for each business model.
  • API Reference — generated request/response schemas for every endpoint, always in sync with the OpenAPI spec.

This section covers the platform, account, and conversation models that aren't part of the business catalog.

Service Configuration​

Core Configuration​

ModelDescription
Agent ConfigurationAI agent behavior and capabilities
Instruction ConfigurationBehavioral guidelines and prompts
Deployment ConfigurationCentral deployment composition
Knowledge SourceDomain knowledge for agents

Channels & Telephony​

ModelDescription
Interaction ChannelsDeployment channels (call, SMS, web, mobile)
Phone ConfigurationPhone number resource management
Phone NumberPhone number purchase and discovery

Voice & Language​

ModelDescription
Voice & LanguageVoices and languages for TTS/STT
Provisioning ConfigVoice processing chains (STT → Agent → TTS)
Support LLMWIIL Platform model registry

Dynamic Setup​

ModelDescription
Dynamic SetupStreamlined agent setup for phone/web

Conversation​

Sessions & Messages​

ModelDescription
Conversation ConfigurationConversation sessions and state management
Conversation MessageChat and email message schemas

Translation Services​

ModelDescription
TranslationReal-time language translation sessions

Common Patterns​

Entity Timestamps​

All entities include standard timestamp fields:

{
  created_at?: number;      // Unix timestamp (milliseconds)
  updated_at?: number;      // Unix timestamp (milliseconds)
  deleted_at?: number;      // Soft delete timestamp
  created_day?: string;     // YYYY-MM-DD format
}

Organization Context​

All entities are scoped to organization and project:

{
  organization_id: string;  // Account identifier
  project_id: string;       // Project identifier
}

Status Enumerations​

Consistent status patterns across entities:

type ConversationStatus =
  | 'ACTIVE'
  | 'COMPLETED'
  | 'TRANSFERRED'
  | 'ABANDONED'
  | 'FAILED';

type TransactionStatus =
  | 'PENDING'
  | 'CONFIRMED'
  | 'COMPLETED'
  | 'CANCELLED';

Using Schemas​

TypeScript Integration Example​

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

// Type-safe conversation creation
const conversation: ServiceConversationConfigSchema = {
  id: 'conv_123',
  organization_id: 'org_123',
  project_id: 'proj_123',
  channel_id: 'ch_123',
  deployment_config_id: 'deploy_123',
  conversation_type: 'OTT_CHAT',
  channel_identifier: '+1234567890',
  durationInSeconds: 0,
};

Runtime Validation Example​

import { z } from 'zod';

const ConversationSchema = z.object({
  id: z.string(),
  organization_id: z.string(),
  project_id: z.string(),
  conversation_type: z.enum(['OTT_CHAT', 'TELEPHONY_CALL', 'SMS', 'EMAIL']),
  // ... additional fields
});

// Validate API response
const result = ConversationSchema.safeParse(apiResponse);
if (result.success) {
  console.log('Valid conversation:', result.data);
}

JavaScript/TypeScript Validation Rules​

Required vs Optional​

Fields marked with ? are optional:

{
  id: string;                  // Required
  customer_id?: string;        // Optional
  instruction_config_id?: string;  // Optional
}

String Formats​

Common string format validations:

{
  email: string;              // Email format
  phone: string;              // E.164 format: +1234567890
  url: string;                // Valid URL
  uuid: string;               // UUID v4 format
  iso_datetime: string;       // ISO 8601 format
}

Nested Objects​

Complex nested structures:

{
  conversationSummary?: {
    summary: string;
    key_points: string[];
    action_items: string[];
    sentiment: 'POSITIVE' | 'NEUTRAL' | 'NEGATIVE' | 'MIXED';
  };
}

Best Practices​

Type Safety​

✅ DO: Use TypeScript types from schemas

import { ServiceConversationConfigSchema } from 'wiil-core-js';
const conversation: ServiceConversationConfigSchema = { ... };

❌ DON'T: Use any or skip types

const conversation: any = { ... };  // Loses type safety

Validation​

✅ DO: Validate API responses

const result = ConversationSchema.safeParse(response);
if (!result.success) {
  console.error('Validation errors:', result.error);
}

❌ DON'T: Trust API responses blindly

const conversation = response as Conversation;  // Unsafe

Optional Fields​

✅ DO: Handle optional fields gracefully

const customerId = conversation.customer_id ?? 'anonymous';

❌ DON'T: Assume optional fields exist

const customerId = conversation.customer_id.toLowerCase();  // May crash

Next Steps​

🔌 Integration Guides

Learn how to integrate schemas in your application

View Guides

📡 API Reference

Explore complete API endpoint documentation

View API Docs

Additional Resources​