Dynamic Agent Setup Guide

Simplified, single-call AI agent deployment

This guide covers the Dynamic Agent Setup API - a streamlined approach to deploying AI agents that abstracts the multi-step configuration process into single API calls.

Introduction
Quick Start
Phone Agent Setup
Web Agent Setup
Updating Configurations
Voice Configuration (STT/TTS)
Role Templates & Capabilities
Error Handling
Best Practices

Introduction

What is Dynamic Agent Setup?

The Dynamic Agent Setup API provides a simplified alternative to the traditional Fundamental Configuration Setup workflow. Instead of making 7+ separate API calls to create instruction configs, agent configs, deployment channels, and deployment configurations, you can deploy a fully functional AI agent with a single API call.

Comparison

Traditional Setup	Dynamic Setup
7+ separate API calls	Single API call
Create instruction config	Auto-generated
Create agent config	Auto-generated
Create deployment channel	Auto-generated
Create deployment config	Auto-generated
Manual linking	Automatic

When to Use Dynamic Setup

Choose Dynamic Setup when:

Rapid prototyping and testing
Standard use cases without complex customization
Quick deployments for demos or MVPs
You want simplicity over granular control

Choose Traditional Setup when:

You need fine-grained control over each configuration
Custom instruction configurations with detailed guidelines
Complex multi-agent deployments
Advanced deployment channel configurations

Prerequisites

WIIL Platform Account - Sign up at https://console.wiil.io
API Key - Generate in Settings → API Keys

SDK Installation

TypeScript
Python

npm install wiil-js
# or
yarn add wiil-js

pip install wiil-python

Quick Start

Minimal Phone Agent

TypeScript
Python

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

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

const result = await client.dynamicPhoneAgent.create({
  assistantName: 'Sarah',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});

console.log('Phone number:', result.phoneNumber);
console.log('Agent ID:', result.agentConfigurationId);

import os
from wiil import WiilClient
from wiil.models.service_mgt import BusinessSupportServices

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

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

print('Phone number:', result.phone_number)
print('Agent ID:', result.agent_configuration_id)

Minimal Web Agent

TypeScript
Python

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

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

const result = await client.dynamicWebAgent.create({
  assistantName: 'Emma',
  websiteUrl: 'https://example.com',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});

console.log('Integration snippets:', result.integrationSnippets);
console.log('Agent ID:', result.agentConfigurationId);

import os
from wiil import WiilClient
from wiil.models.service_mgt import BusinessSupportServices

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

result = client.dynamic_web_agent.create(
    assistant_name='Emma',
    website_url='https://example.com',
    capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT]
)

print('Integration snippets:', result.integration_snippets)
print('Agent ID:', result.agent_configuration_id)

Phone Agent Setup

Overview

The Dynamic Phone Agent API provisions a phone-based AI agent with automatic phone number assignment.

Required Fields

Field	Type	Description
`assistantName`	`string`	Name of the AI assistant
`capabilities`	`BusinessSupportServices[]`	Platform services enabled for this agent

Optional Fields

Field	Type	Description
`role_template_identifier`	`AgentRoleTemplateIdentifier`	Role/persona for the agent
`language`	`string`	Language code (default: `"en"`)
`phoneConfigurationId`	`string`	Existing phone configuration to use
`testPhoneNumber`	`string`	Phone number for testing
`instructionConfigurationId`	`string`	Existing instruction config to use
`knowledgeSourceIds`	`string[]`	Knowledge sources to associate
`voice`	`string`	Voice ID for the assistant
`providerType`	`SupportedProprietor`	AI model provider
`providerModelId`	`string`	Specific model ID
`sttConfiguration`	`object`	Speech-to-text config
`ttsConfiguration`	`object`	Text-to-speech config

Full Example with Voice

TypeScript
Python

import { WiilClient } from 'wiil-js';
import {
  BusinessSupportServices,
  AgentRoleTemplateIdentifier,
  SupportedProprietor
} from 'wiil-core-js';

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

const result = await client.dynamicPhoneAgent.create({
  // Required
  assistantName: 'Marcus',
  capabilities: [
    BusinessSupportServices.APPOINTMENT_MANAGEMENT,
    BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT
  ],

  // Optional - Role & Language
  role_template_identifier: AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,
  language: 'en-US',

  // Optional - Phone Configuration
  phoneConfigurationId: 'phone_config_123',

  // Optional - Voice Configuration
  sttConfiguration: {
    providerType: SupportedProprietor.DEEPGRAM,
    providerModelId: 'nova-2',
    languageId: 'en-US'
  },
  ttsConfiguration: {
    providerType: SupportedProprietor.ELEVENLABS,
    providerModelId: 'eleven_turbo_v2',
    languageId: 'en-US',
    voiceId: 'voice_rachel'
  }
});

console.log('Setup successful:', result.success);
console.log('Phone number:', result.phoneNumber);
console.log('Agent Config ID:', result.agentConfigurationId);
console.log('Instruction Config ID:', result.instructionConfigurationId);

import os
from wiil import WiilClient
from wiil.models.service_mgt import (
    BusinessSupportServices,
    AgentRoleTemplateIdentifier,
    SupportedProprietor,
    DynamicSTTModelConfiguration,
    DynamicTTSModelConfiguration
)

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

result = client.dynamic_phone_agent.create(
    # Required
    assistant_name='Marcus',
    capabilities=[
        BusinessSupportServices.APPOINTMENT_MANAGEMENT,
        BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT
    ],

    # Optional - Role & Language
    role_template_identifier=AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,
    language='en-US',

    # Optional - Phone Configuration
    phone_configuration_id='phone_config_123',

    # Optional - Voice Configuration
    stt_configuration=DynamicSTTModelConfiguration(
        provider_type=SupportedProprietor.DEEPGRAM.value,
        provider_model_id='nova-2',
        language_id='en-US'
    ),
    tts_configuration=DynamicTTSModelConfiguration(
        provider_type=SupportedProprietor.ELEVENLABS.value,
        provider_model_id='eleven_turbo_v2',
        language_id='en-US',
        voice_id='voice_rachel'
    )
)

print('Setup successful:', result.success)
print('Phone number:', result.phone_number)
print('Agent Config ID:', result.agent_configuration_id)
print('Instruction Config ID:', result.instruction_configuration_id)

Result Type

The DynamicPhoneAgentSetupResult includes:

Field	Type	Description
`success`	`boolean`	Whether setup succeeded
`agentConfigurationId`	`string`	Created agent config ID
`instructionConfigurationId`	`string`	Created instruction config ID
`phoneNumber`	`string`	Provisioned phone number
`errorMessage`	`string?`	Error message if failed
`metadata`	`object?`	Additional metadata

CRUD Operations

TypeScript
Python

// Create
const created = await client.dynamicPhoneAgent.create({ ... });

// Update (partial)
const updated = await client.dynamicPhoneAgent.update({
  id: 'agent_123',
  assistantName: 'Nathan'
});

// Delete
const deleted = await client.dynamicPhoneAgent.delete('agent_123');

# Create
created = client.dynamic_phone_agent.create(...)

# Update (partial)
updated = client.dynamic_phone_agent.update(
    id='agent_123',
    assistant_name='Nathan'
)

# Delete
deleted = client.dynamic_phone_agent.delete('agent_123')

Web Agent Setup

Overview

The Dynamic Web Agent API provisions a web-based AI agent with integration snippets for website embedding.

Required Fields

Field	Type	Description
`assistantName`	`string`	Name of the AI assistant
`websiteUrl`	`string`	URL of the website
`capabilities`	`BusinessSupportServices[]`	Platform services enabled

Optional Fields

Field	Type	Description
`communicationType`	`OttCommunicationType`	TEXT, VOICE, or UNIFIED (default: UNIFIED)
`widgetConfiguration`	`object`	Chat widget appearance & behavior as a key-value map (see Widget Configuration)
`role_template_identifier`	`AgentRoleTemplateIdentifier`	Role/persona for the agent
`language`	`string`	Language code (default: `"en"`)
`instructionConfigurationId`	`string`	Existing instruction config
`knowledgeSourceIds`	`string[]`	Existing knowledge sources to associate by ID
`textKnowledgeSource`	`object`	New knowledge source created inline from raw text (see Knowledge Sources)
`voice`	`string`	Voice ID
`providerType`	`SupportedProprietor`	AI model provider
`providerModelId`	`string`	Specific model ID
`sttConfiguration`	`object`	Speech-to-text config
`ttsConfiguration`	`object`	Text-to-speech config

Communication Types

TypeScript
Python

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

// Text-only chat
communicationType: OttCommunicationType.TEXT

// Voice-only interaction
communicationType: OttCommunicationType.VOICE

// Combined text and voice (default)
communicationType: OttCommunicationType.UNIFIED

from wiil.models.service_mgt import OttCommunicationType

# Text-only chat
communication_type = OttCommunicationType.TEXT

# Voice-only interaction
communication_type = OttCommunicationType.VOICE

# Combined text and voice (default)
communication_type = OttCommunicationType.UNIFIED

Knowledge Sources

Ground a web agent in a knowledge base at setup time. Two options are available and can be combined:

knowledgeSourceIds — link existing knowledge sources by ID.
textKnowledgeSource — create a brand-new knowledge source from raw text inline, without pre-creating it. The new source is attached to the agent's generated instruction configuration (and therefore its agent configuration), so it is queryable as soon as setup completes.

`textKnowledgeSource` Fields

Field	Type	Required	Description
`name`	`string \| null`	No	Optional human-readable name for the text knowledge source
`content`	`string`	Yes	Raw text content to create as a new knowledge source (min 1 character)

TypeScript
Python

const result = await client.dynamicWebAgent.create({
  assistantName: 'Maya',
  websiteUrl: 'https://www.example.com',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
  role_template_identifier: AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,

  // Link existing knowledge sources
  knowledgeSourceIds: ['knowledge_help_center'],

  // Create a new knowledge source inline
  textKnowledgeSource: {
    name: 'Return Policy',
    content: 'Customers may return unused items within 30 days of purchase with a receipt for a full refund.'
  }
});

from wiil.models.service_mgt import (
    BusinessSupportServices,
    AgentRoleTemplateIdentifier,
    TextBasedKnowledgeSource
)

result = client.dynamic_web_agent.create(
    assistant_name='Maya',
    website_url='https://www.example.com',
    capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
    role_template_identifier=AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,

    # Link existing knowledge sources
    knowledge_source_ids=['knowledge_help_center'],

    # Create a new knowledge source inline
    text_knowledge_source=TextBasedKnowledgeSource(
        name='Return Policy',
        content='Customers may return unused items within 30 days of purchase with a receipt for a full refund.'
    )
)

For web agents, widgetConfiguration sets the appearance and behavior of the embedded chat widget. It is a key-value string map whose keys are widget properties — for example primaryColor, widgetTitle, position, theme, and features. See the Widget Configuration Guide for the complete list of properties and their accepted values.

TypeScript
Python

const result = await client.dynamicWebAgent.create({
  assistantName: 'Maya',
  websiteUrl: 'https://www.example.com',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
  communicationType: OttCommunicationType.UNIFIED,
  widgetConfiguration: {
    primaryColor: '#0d9488',
    widgetTitle: 'Chat with Maya',
    position: 'bottom-right',
    theme: 'light',
    features: 'chat,voice'
  }
});

result = client.dynamic_web_agent.create(
    assistant_name='Maya',
    website_url='https://www.example.com',
    capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
    communication_type=OttCommunicationType.UNIFIED,
    widget_configuration={
        'primaryColor': '#0d9488',
        'widgetTitle': 'Chat with Maya',
        'position': 'bottom-right',
        'theme': 'light',
        'features': 'chat,voice'
    }
)

Full Example with Voice

TypeScript
Python

import { WiilClient } from 'wiil-js';
import {
  BusinessSupportServices,
  AgentRoleTemplateIdentifier,
  OttCommunicationType,
  SupportedProprietor
} from 'wiil-core-js';

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

const result = await client.dynamicWebAgent.create({
  // Required
  assistantName: 'Olivia',
  websiteUrl: 'https://example.com',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],

  // Optional - Communication Type
  communicationType: OttCommunicationType.UNIFIED,

  // Optional - Role & Language
  role_template_identifier: AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,
  language: 'en-US',

  // Optional - Voice Configuration
  sttConfiguration: {
    providerType: SupportedProprietor.DEEPGRAM,
    providerModelId: 'nova-2',
    languageId: 'en-US'
  },
  ttsConfiguration: {
    providerType: SupportedProprietor.ELEVENLABS,
    providerModelId: 'eleven_turbo_v2',
    languageId: 'en-US',
    voiceId: 'voice_rachel'
  }
});

console.log('Setup successful:', result.success);
console.log('Agent Config ID:', result.agentConfigurationId);
console.log('Integration snippets:');
result.integrationSnippets.forEach((snippet, i) => {
  console.log(`  Snippet ${i + 1}:`, snippet);
});

import os
from wiil import WiilClient
from wiil.models.service_mgt import (
    BusinessSupportServices,
    AgentRoleTemplateIdentifier,
    OttCommunicationType,
    SupportedProprietor,
    DynamicSTTModelConfiguration,
    DynamicTTSModelConfiguration
)

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

result = client.dynamic_web_agent.create(
    # Required
    assistant_name='Olivia',
    website_url='https://example.com',
    capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],

    # Optional - Communication Type
    communication_type=OttCommunicationType.UNIFIED,

    # Optional - Role & Language
    role_template_identifier=AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,
    language='en-US',

    # Optional - Voice Configuration
    stt_configuration=DynamicSTTModelConfiguration(
        provider_type=SupportedProprietor.DEEPGRAM.value,
        provider_model_id='nova-2',
        language_id='en-US'
    ),
    tts_configuration=DynamicTTSModelConfiguration(
        provider_type=SupportedProprietor.ELEVENLABS.value,
        provider_model_id='eleven_turbo_v2',
        language_id='en-US',
        voice_id='voice_rachel'
    )
)

print('Setup successful:', result.success)
print('Agent Config ID:', result.agent_configuration_id)
print('Integration snippets:')
for i, snippet in enumerate(result.integration_snippets):
    print(f'  Snippet {i + 1}:', snippet)

Result Type

The DynamicWebAgentSetupResult includes:

Field	Type	Description
`success`	`boolean`	Whether setup succeeded
`agentConfigurationId`	`string`	Created agent config ID
`instructionConfigurationId`	`string`	Created instruction config ID
`integrationSnippets`	`string[]`	Code snippets for embedding
`errorMessage`	`string?`	Error message if failed
`metadata`	`object?`	Additional metadata

Website Integration

Use the returned integration snippets in your HTML:

Customize the widget

The embedded widget's appearance and behavior — theme, colors, position, contact form, and more — are set via data-* attributes. See the Widget Configuration Guide for all options.

TypeScript
Python

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to Our Website</h1>

  <!-- WIIL Widget - paste integration snippets here -->
  <script src="https://cdn.wiil.io/widget.js"></script>
  <div id="wiil-widget" data-agent="agent_123"></div>
  <script>WiilWidget.init({ agentId: "agent_123" });</script>
</body>
</html>

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to Our Website</h1>

  <!-- WIIL Widget - paste integration snippets here -->
  <script src="https://cdn.wiil.io/widget.js"></script>
  <div id="wiil-widget" data-agent="agent_123"></div>
  <script>WiilWidget.init({ agentId: "agent_123" });</script>
</body>
</html>

CRUD Operations

TypeScript
Python

// Create
const created = await client.dynamicWebAgent.create({ ... });

// Update (partial)
const updated = await client.dynamicWebAgent.update({
  id: 'agent_123',
  assistantName: 'Sophia',
  communicationType: OttCommunicationType.TEXT
});

// Delete
const deleted = await client.dynamicWebAgent.delete('agent_123');

// Get integration snippets separately
const snippets = await client.dynamicWebAgent.getIntegrationSnippets('agent_123');

# Create
created = client.dynamic_web_agent.create(...)

# Update (partial)
updated = client.dynamic_web_agent.update(
    id='agent_123',
    assistant_name='Sophia',
    communication_type=OttCommunicationType.TEXT
)

# Delete
deleted = client.dynamic_web_agent.delete('agent_123')

# Get integration snippets separately
snippets = client.dynamic_web_agent.get_integration_snippets('agent_123')

Updating Configurations

Partial Updates

Both phone and web agents support partial updates. Only include the fields you want to change, plus the required id field.

TypeScript
Python

// Update phone agent
const updatedPhone = await client.dynamicPhoneAgent.update({
  id: 'agent_123',
  assistantName: 'Carlos',
  language: 'es-MX'
});

// Update web agent
const updatedWeb = await client.dynamicWebAgent.update({
  id: 'agent_456',
  websiteUrl: 'https://new-website.com',
  communicationType: OttCommunicationType.VOICE
});

# Update phone agent
updated_phone = client.dynamic_phone_agent.update(
    id='agent_123',
    assistant_name='Carlos',
    language='es-MX'
)

# Update web agent
updated_web = client.dynamic_web_agent.update(
    id='agent_456',
    website_url='https://new-website.com',
    communication_type=OttCommunicationType.VOICE
)

Update Voice Configuration

TypeScript
Python

const updated = await client.dynamicPhoneAgent.update({
  id: 'agent_123',
  sttConfiguration: {
    providerType: SupportedProprietor.GOOGLE,
    providerModelId: 'chirp',
    languageId: 'en-US'
  },
  ttsConfiguration: {
    providerType: SupportedProprietor.ELEVENLABS,
    providerModelId: 'eleven_multilingual_v2',
    languageId: 'en-US',
    voiceId: 'voice_adam'
  }
});

from wiil.models.service_mgt import (
    SupportedProprietor,
    DynamicSTTModelConfiguration,
    DynamicTTSModelConfiguration
)

updated = client.dynamic_phone_agent.update(
    id='agent_123',
    stt_configuration=DynamicSTTModelConfiguration(
        provider_type=SupportedProprietor.GOOGLE.value,
        provider_model_id='chirp',
        language_id='en-US'
    ),
    tts_configuration=DynamicTTSModelConfiguration(
        provider_type=SupportedProprietor.ELEVENLABS.value,
        provider_model_id='eleven_multilingual_v2',
        language_id='en-US',
        voice_id='voice_adam'
    )
)

Voice Configuration (STT/TTS)

Overview

Both phone and web agents support voice interactions through Speech-to-Text (STT) and Text-to-Speech (TTS) configurations.

Important: STT and TTS configurations must be provided together or neither. You cannot configure one without the other.

STT Configuration

TypeScript
Python

sttConfiguration: {
  providerType: SupportedProprietor.DEEPGRAM,  // Required
  providerModelId: 'nova-2',                    // Required
  languageId: 'en-US'                           // Optional, default: 'en'
}

from wiil.models.service_mgt import (
    SupportedProprietor,
    DynamicSTTModelConfiguration
)

stt_configuration = DynamicSTTModelConfiguration(
    provider_type=SupportedProprietor.DEEPGRAM.value,  # Required
    provider_model_id='nova-2',                         # Required
    language_id='en-US'                                 # Optional, default: 'en'
)

TTS Configuration

TypeScript
Python

ttsConfiguration: {
  providerType: SupportedProprietor.ELEVENLABS, // Required
  providerModelId: 'eleven_turbo_v2',           // Required
  languageId: 'en-US',                          // Optional, default: 'en'
  voiceId: 'voice_rachel'                       // Optional
}

from wiil.models.service_mgt import (
    SupportedProprietor,
    DynamicTTSModelConfiguration
)

tts_configuration = DynamicTTSModelConfiguration(
    provider_type=SupportedProprietor.ELEVENLABS.value,  # Required
    provider_model_id='eleven_turbo_v2',                 # Required
    language_id='en-US',                                 # Optional, default: 'en'
    voice_id='voice_rachel'                              # Optional
)

Supported Providers

TypeScript
Python

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

// Available providers
SupportedProprietor.OPENAI      // "OpenAI"
SupportedProprietor.GOOGLE      // "Google"
SupportedProprietor.ANTHROPIC   // "Anthropic"
SupportedProprietor.GROQ        // "Groq"
SupportedProprietor.DEEPGRAM    // "Deepgram" - Recommended for STT
SupportedProprietor.ELEVENLABS  // "ElevenLabs" - Recommended for TTS
SupportedProprietor.CARTESIA    // "Cartesia"

from wiil.models.service_mgt import SupportedProprietor

# Available providers
SupportedProprietor.OPENAI      # "OpenAI"
SupportedProprietor.GOOGLE      # "Google"
SupportedProprietor.ANTHROPIC   # "Anthropic"
SupportedProprietor.GROQ        # "Groq"
SupportedProprietor.DEEPGRAM    # "Deepgram" - Recommended for STT
SupportedProprietor.ELEVENLABS  # "ElevenLabs" - Recommended for TTS
SupportedProprietor.CARTESIA    # "Cartesia"

Recommended Configurations

For STT (Speech-to-Text):

TypeScript
Python

sttConfiguration: {
  providerType: SupportedProprietor.DEEPGRAM,
  providerModelId: 'nova-2',
  languageId: 'en-US'
}

stt_configuration = DynamicSTTModelConfiguration(
    provider_type=SupportedProprietor.DEEPGRAM.value,
    provider_model_id='nova-2',
    language_id='en-US'
)

For TTS (Text-to-Speech):

TypeScript
Python

ttsConfiguration: {
  providerType: SupportedProprietor.ELEVENLABS,
  providerModelId: 'eleven_turbo_v2',
  languageId: 'en-US',
  voiceId: 'voice_rachel'  // Choose appropriate voice
}

tts_configuration = DynamicTTSModelConfiguration(
    provider_type=SupportedProprietor.ELEVENLABS.value,
    provider_model_id='eleven_turbo_v2',
    language_id='en-US',
    voice_id='voice_rachel'  # Choose appropriate voice
)

Role Templates & Capabilities

Agent Role Templates

Role templates define the agent's persona and behavior style:

TypeScript
Python

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

// Available role templates
AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL      // General customer support
AgentRoleTemplateIdentifier.TECHNICAL_SUPPORT_SPECIALIST  // Technical assistance
AgentRoleTemplateIdentifier.SALES_REPRESENTATIVE          // Sales and lead generation
AgentRoleTemplateIdentifier.ONBOARDING_SPECIALIST         // Customer onboarding
AgentRoleTemplateIdentifier.BILLING_SUPPORT_SPECIALIST    // Billing and payments

from wiil.models.service_mgt import AgentRoleTemplateIdentifier

# Available role templates
AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL      # General customer support
AgentRoleTemplateIdentifier.TECHNICAL_SUPPORT_SPECIALIST  # Technical assistance
AgentRoleTemplateIdentifier.SALES_REPRESENTATIVE          # Sales and lead generation
AgentRoleTemplateIdentifier.ONBOARDING_SPECIALIST         # Customer onboarding
AgentRoleTemplateIdentifier.BILLING_SUPPORT_SPECIALIST    # Billing and payments

Business Capabilities

Capabilities define which platform services (tools) the agent can use:

TypeScript
Python

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

// Available capabilities
BusinessSupportServices.APPOINTMENT_MANAGEMENT    // Appointment scheduling
BusinessSupportServices.INVENTORY_MANAGEMENT      // Inventory tracking
BusinessSupportServices.MENU_ORDER_MANAGEMENT     // Restaurant menu orders
BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT  // Product/retail orders
BusinessSupportServices.RESERVATION_MANAGEMENT    // Table/room reservations
BusinessSupportServices.PROPERTY_MANAGEMENT       // Property listings
BusinessSupportServices.NONE                      // No business services

from wiil.models.service_mgt import BusinessSupportServices

# Available capabilities
BusinessSupportServices.APPOINTMENT_MANAGEMENT    # Appointment scheduling
BusinessSupportServices.INVENTORY_MANAGEMENT      # Inventory tracking
BusinessSupportServices.MENU_ORDER_MANAGEMENT     # Restaurant menu orders
BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT  # Product/retail orders
BusinessSupportServices.RESERVATION_MANAGEMENT    # Table/room reservations
BusinessSupportServices.PROPERTY_MANAGEMENT       # Property listings
BusinessSupportServices.NONE                      # No business services

Example: E-commerce Support Agent

TypeScript
Python

const result = await client.dynamicWebAgent.create({
  assistantName: 'Ava',
  websiteUrl: 'https://shop.example.com',
  capabilities: [
    BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT,
    BusinessSupportServices.INVENTORY_MANAGEMENT
  ],
  role_template_identifier: AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL
});

result = client.dynamic_web_agent.create(
    assistant_name='Ava',
    website_url='https://shop.example.com',
    capabilities=[
        BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT,
        BusinessSupportServices.INVENTORY_MANAGEMENT
    ],
    role_template_identifier=AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL
)

Example: Restaurant Agent

TypeScript
Python

const result = await client.dynamicPhoneAgent.create({
  assistantName: 'Mia',
  capabilities: [
    BusinessSupportServices.RESERVATION_MANAGEMENT,
    BusinessSupportServices.MENU_ORDER_MANAGEMENT
  ],
  role_template_identifier: AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL
});

result = client.dynamic_phone_agent.create(
    assistant_name='Mia',
    capabilities=[
        BusinessSupportServices.RESERVATION_MANAGEMENT,
        BusinessSupportServices.MENU_ORDER_MANAGEMENT
    ],
    role_template_identifier=AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL
)

Error Handling

Error Types

TypeScript
Python

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

try {
  const result = await client.dynamicPhoneAgent.create({
    assistantName: 'Liam',
    capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT]
  });
} catch (error) {
  if (error instanceof WiilValidationError) {
    // Invalid input data
    console.error('Validation failed:', error.details);
  } else if (error instanceof WiilAPIError) {
    // API returned an error
    console.error(`API Error ${error.statusCode}:`, error.message);
  } else if (error instanceof WiilNetworkError) {
    // Network connectivity issue
    console.error('Network error:', error.message);
  }
}

from wiil.errors import (
    WiilAPIError,
    WiilValidationError,
    WiilNetworkError
)

try:
    result = client.dynamic_phone_agent.create(
        assistant_name='Liam',
        capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT]
    )
except WiilValidationError as error:
    # Invalid input data
    print('Validation failed:', error.details)
except WiilAPIError as error:
    # API returned an error
    print(f'API Error {error.status_code}:', error.message)
except WiilNetworkError as error:
    # Network connectivity issue
    print('Network error:', error.message)

Common Errors

Error	Cause	Solution
400 Bad Request	Invalid input data	Check required fields and enum values
401 Unauthorized	Invalid API key	Verify API key is correct and active
404 Not Found	Agent ID doesn't exist	Verify the agent ID is correct
422 Validation Error	STT/TTS mismatch	Provide both STT and TTS configs together

STT/TTS Validation

Both configurations must be provided together or neither:

TypeScript
Python

// Valid: Both provided
{
  sttConfiguration: { ... },
  ttsConfiguration: { ... }
}

// Valid: Neither provided
{
  // No STT/TTS config
}

// Invalid: Only one provided - will throw validation error
{
  sttConfiguration: { ... }
  // Missing ttsConfiguration
}

# Valid: Both provided
create_args = {
    'stt_configuration': DynamicSTTModelConfiguration(...),
    'tts_configuration': DynamicTTSModelConfiguration(...)
}

# Valid: Neither provided
create_args = {
    # No STT/TTS config
}

# Invalid: Only one provided - will throw validation error
create_args = {
    'stt_configuration': DynamicSTTModelConfiguration(...)
    # Missing tts_configuration
}

Best Practices

1. Naming Conventions

Use actual personal names for a natural, human-like experience:

TypeScript
Python

// Good
assistantName: 'Sarah'
assistantName: 'Alex'
assistantName: 'Emma'

// Avoid
assistantName: 'bot1'
assistantName: 'test'
assistantName: 'Customer Support - Premium Tier'

# Good
assistant_name = 'Sarah'
assistant_name = 'Alex'
assistant_name = 'Emma'

# Avoid
assistant_name = 'bot1'
assistant_name = 'test'
assistant_name = 'Customer Support - Premium Tier'

2. Choose Appropriate Capabilities

Only enable capabilities the agent will actually use:

TypeScript
Python

// Good - specific capabilities for use case
capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT]

// Avoid - enabling everything
capabilities: [
  BusinessSupportServices.APPOINTMENT_MANAGEMENT,
  BusinessSupportServices.INVENTORY_MANAGEMENT,
  BusinessSupportServices.MENU_ORDER_MANAGEMENT,
  BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT,
  BusinessSupportServices.RESERVATION_MANAGEMENT,
  BusinessSupportServices.PROPERTY_MANAGEMENT
]

# Good - specific capabilities for use case
capabilities = [BusinessSupportServices.APPOINTMENT_MANAGEMENT]

# Avoid - enabling everything
capabilities = [
    BusinessSupportServices.APPOINTMENT_MANAGEMENT,
    BusinessSupportServices.INVENTORY_MANAGEMENT,
    BusinessSupportServices.MENU_ORDER_MANAGEMENT,
    BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT,
    BusinessSupportServices.RESERVATION_MANAGEMENT,
    BusinessSupportServices.PROPERTY_MANAGEMENT
]

3. Web vs Phone Channel Selection

Use Phone Agent when:

Primary interaction is voice calls
Customers prefer phone support
Complex issues requiring real-time conversation
Accessibility requirements

Use Web Agent when:

Website-based customer support
E-commerce and online services
Need text and/or voice options
Integration with web applications

4. Voice Configuration

Use Deepgram Nova-2 for high-quality STT
Use ElevenLabs for natural-sounding TTS
Match language IDs across STT and TTS
Test voice quality in development environment

5. Error Handling

Always implement comprehensive error handling in production:

TypeScript
Python

async function createAgent() {
  try {
    const result = await client.dynamicPhoneAgent.create({ ... });

    if (!result.success) {
      console.error('Setup failed:', result.errorMessage);
      return null;
    }

    return result;
  } catch (error) {
    // Handle specific error types
    throw error;
  }
}

def create_agent():
    try:
        result = client.dynamic_phone_agent.create(...)

        if not result.success:
            print('Setup failed:', result.error_message)
            return None

        return result
    except Exception as error:
        # Handle specific error types
        raise error

Support & Resources

Documentation

Platform Docs: https://docs.wiil.io
API Reference: https://docs.wiil.io/developer/api-reference
SDK Reference: https://github.com/wiil-io/wiil-js

Support

Email: dev-support@wiil.io
Console: https://console.wiil.io
GitHub Issues: https://github.com/wiil-io/wiil-js/issues

Fundamental Configuration Setup - Traditional multi-step setup
Voice Channels - Phone call integration
Web Channels - Web chat widget integration

Built with the WIIL team

Table of Contents​

Introduction​

What is Dynamic Agent Setup?​

Comparison​

When to Use Dynamic Setup​

Prerequisites​

Quick Start​

Minimal Phone Agent​

Minimal Web Agent​

Phone Agent Setup​

Overview​

Required Fields​

Optional Fields​

Full Example with Voice​

Result Type​

CRUD Operations​

Web Agent Setup​

Overview​

Required Fields​

Optional Fields​

Communication Types​

Knowledge Sources​

textKnowledgeSource Fields​

Widget Configuration​

Full Example with Voice​

Result Type​

Website Integration​

CRUD Operations​

Updating Configurations​

Partial Updates​

Update Voice Configuration​

Voice Configuration (STT/TTS)​

Overview​

STT Configuration​

TTS Configuration​

Supported Providers​

Recommended Configurations​

Role Templates & Capabilities​

Agent Role Templates​

Business Capabilities​

Example: E-commerce Support Agent​

Example: Restaurant Agent​

Error Handling​

Error Types​

Common Errors​

STT/TTS Validation​

Best Practices​

1. Naming Conventions​

2. Choose Appropriate Capabilities​

3. Web vs Phone Channel Selection​

4. Voice Configuration​

5. Error Handling​

Support & Resources​

Documentation​

Support​

Related Guides​

Table of Contents

Introduction

What is Dynamic Agent Setup?

Comparison

When to Use Dynamic Setup

Prerequisites

Quick Start

Minimal Phone Agent

Minimal Web Agent

Phone Agent Setup

Overview

Required Fields

Optional Fields

Full Example with Voice

Result Type

CRUD Operations

Web Agent Setup

Overview

Required Fields

Optional Fields

Communication Types

Knowledge Sources

`textKnowledgeSource` Fields

Widget Configuration

Full Example with Voice

Result Type

Website Integration

CRUD Operations

Updating Configurations

Partial Updates

Update Voice Configuration

Voice Configuration (STT/TTS)

Overview

STT Configuration

TTS Configuration

Supported Providers

Recommended Configurations

Role Templates & Capabilities

Agent Role Templates

Business Capabilities

Example: E-commerce Support Agent

Example: Restaurant Agent

Error Handling

Error Types

Common Errors

STT/TTS Validation

Best Practices

1. Naming Conventions

2. Choose Appropriate Capabilities

3. Web vs Phone Channel Selection

4. Voice Configuration

5. Error Handling

Support & Resources

Documentation

Support

Related Guides