Dynamic Agents API

Simplified, single-call AI agent deployment.

Overview

The Dynamic Agents API provides a streamlined approach to deploying AI agents that abstracts the multi-step configuration process into single API calls.

Endpoint: /dynamic-agents

Comparison with Traditional Setup

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

Phone Agent

Create Phone Agent

POST /dynamic-agents/phone

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

Example Request

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({
  assistantName: 'Marcus',
  capabilities: [
    BusinessSupportServices.APPOINTMENT_MANAGEMENT,
    BusinessSupportServices.PRODUCT_ORDER_MANAGEMENT
  ],
  role_template_identifier: AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,
  language: 'en-US',
  sttConfiguration: {
    providerType: SupportedProprietor.DEEPGRAM,
    providerModelId: 'nova-2',
    languageId: 'en-US'
  },
  ttsConfiguration: {
    providerType: SupportedProprietor.ELEVENLABS,
    providerModelId: 'eleven_turbo_v2',
    languageId: 'en-US',
    voiceId: 'voice_rachel'
  }
});

Response

interface DynamicPhoneAgentSetupResult {
  success: boolean;
  agentConfigurationId: string;
  instructionConfigurationId: string;
  phoneNumber: string;
  errorMessage?: string;
  metadata?: object;
}

Update Phone Agent

PATCH /dynamic-agents/phone/:id

const updated = await client.dynamicPhoneAgent.update({
  id: 'agent_123',
  assistantName: 'Nathan',
  language: 'es-MX'
});

Delete Phone Agent

DELETE /dynamic-agents/phone/:id

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

Web Agent

Create Web Agent

POST /dynamic-agents/web

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)
`role_template_identifier`	`AgentRoleTemplateIdentifier`	Role/persona for the agent
`language`	`string`	Language code (default: `"en"`)
`instructionConfigurationId`	`string`	Existing instruction config
`knowledgeSourceIds`	`string[]`	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

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

OttCommunicationType.TEXT     // Text-only chat
OttCommunicationType.VOICE    // Voice-only interaction
OttCommunicationType.UNIFIED  // Combined text and voice (default)

Example Request

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({
  assistantName: 'Olivia',
  websiteUrl: 'https://example.com',
  capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
  communicationType: OttCommunicationType.UNIFIED,
  role_template_identifier: AgentRoleTemplateIdentifier.CUSTOMER_SUPPORT_GENERAL,
  language: 'en-US',
  sttConfiguration: {
    providerType: SupportedProprietor.DEEPGRAM,
    providerModelId: 'nova-2',
    languageId: 'en-US'
  },
  ttsConfiguration: {
    providerType: SupportedProprietor.ELEVENLABS,
    providerModelId: 'eleven_turbo_v2',
    languageId: 'en-US',
    voiceId: 'voice_rachel'
  }
});

Response

interface DynamicWebAgentSetupResult {
  success: boolean;
  agentConfigurationId: string;
  instructionConfigurationId: string;
  integrationSnippets: string[];
  errorMessage?: string;
  metadata?: object;
}

Website Integration

Use the returned integration snippets in your 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 -->
  <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>

Update Web Agent

PATCH /dynamic-agents/web/:id

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

Delete Web Agent

DELETE /dynamic-agents/web/:id

const deleted = await client.dynamicWebAgent.delete('agent_456');

Get Integration Snippets

GET /dynamic-agents/web/:id/snippets

const snippets = await client.dynamicWebAgent.getIntegrationSnippets('agent_123');

Voice Configuration

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

warning

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

STT Configuration

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

TTS Configuration

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

Supported Providers

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

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

Role Templates & Capabilities

Agent Role Templates

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

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

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

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

Error Handling

Error Types

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) {
    console.error('Validation failed:', error.details);
  } else if (error instanceof WiilAPIError) {
    console.error(`API Error ${error.statusCode}:`, error.message);
  } else if (error instanceof WiilNetworkError) {
    console.error('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

Best Practices

Naming Conventions

Use actual personal names for a natural experience:

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

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

Capability Selection

Only enable capabilities the agent will actually use:

// Good - specific capabilities
capabilities: [BusinessSupportServices.APPOINTMENT_MANAGEMENT]

// Avoid - enabling everything unnecessarily
capabilities: [
  BusinessSupportServices.APPOINTMENT_MANAGEMENT,
  BusinessSupportServices.INVENTORY_MANAGEMENT,
  BusinessSupportServices.MENU_ORDER_MANAGEMENT,
  // ...
]

Channel Selection

Use Phone Agent when:

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

Use Web Agent when:

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

Overview​

Comparison with Traditional Setup​

When to Use Dynamic Setup​

Phone Agent​

Create Phone Agent​

Required Fields​

Optional Fields​

Example Request​

Response​

Update Phone Agent​

Delete Phone Agent​

Web Agent​

Create Web Agent​

Required Fields​

Optional Fields​

Communication Types​

Example Request​

Response​

Website Integration​

Update Web Agent​

Delete Web Agent​

Get Integration Snippets​

Voice Configuration​

STT Configuration​

TTS Configuration​

Supported Providers​

Role Templates & Capabilities​

Agent Role Templates​

Business Capabilities​

Error Handling​

Error Types​

Common Errors​

Best Practices​

Naming Conventions​

Capability Selection​

Channel Selection​

Overview

Comparison with Traditional Setup

When to Use Dynamic Setup

Phone Agent

Create Phone Agent

Required Fields

Optional Fields

Example Request

Response

Update Phone Agent

Delete Phone Agent

Web Agent

Create Web Agent

Required Fields

Optional Fields

Communication Types

Example Request

Response

Website Integration

Update Web Agent

Delete Web Agent

Get Integration Snippets

Voice Configuration

STT Configuration

TTS Configuration

Supported Providers

Role Templates & Capabilities

Agent Role Templates

Business Capabilities

Error Handling

Error Types

Common Errors

Best Practices

Naming Conventions

Capability Selection

Channel Selection