Skip to main content

Voice Call Channels Guide

Set up AI-powered voice calls on your phone number

Setup Time: ~5 minutes (including phone purchase)

Overview​

Voice channels enable AI agents to handle phone calls. They are automatically created when you purchase a phone number.

Prerequisites​

Before setting up voice channels:

  1. ✅ Active WIIL Platform account
  2. ✅ Sufficient account credits
  3. ✅ Project ID
  4. ✅ Agent Configuration ID
  5. ✅ Instruction Configuration ID

Quick Start​

Step 0: Find Available Phone Numbers​

Before purchasing, search for available phone numbers.

import { WiilClient } from 'wiil-js';

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

// Search for phone numbers
const numbers = await client.telephonyProvider.getPhoneNumbers();

console.log(`Found ${numbers.length} available numbers`);

// Search with filters
const filteredNumbers = await client.telephonyProvider.getPhoneNumbers({
  areaCode: '212'
});

// Get pricing
const pricing = await client.telephonyProvider.getPricing();

console.log('Pricing:', pricing);

📖 See Full Guide: Phone Purchase Guide for complete details on searching and purchasing phone numbers.

Step 1: Purchase Phone Number​

Voice channels are created automatically when you purchase a phone number.

import { WiilClient } from 'wiil-js';

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

const phonePurchase = await client.telephonyProvider.purchase({
  phoneNumber: '+12125551234',
  friendlyName: 'Customer Support Line' // Optional
});

console.log(`Purchase ID: ${phonePurchase.id}`);
console.log('Processing... (under 5 minutes)');

Step 2: Get Voice Channel ID​

After purchase completes, retrieve the phone configuration to get the voiceChannelId.

// Wait for purchase to complete (under 5 minutes)
await new Promise(resolve => setTimeout(resolve, 300000));

const phoneConfig = await client.phoneConfigs.getByPhoneNumber('+12125551234');

console.log('Phone Configuration:');
console.log(`  Voice Channel ID: ${phoneConfig.voiceChannelId}`);
console.log(`  SMS Channel ID: ${phoneConfig.smsChannelId}`);
console.log(`  Status: ${phoneConfig.status}`);

Output:

Phone Configuration:
  Voice Channel ID: 2s3t4u5v6w7x8y9z0a1b
  SMS Channel ID: 3t4u5v6w7x8y9z0a1b2c
  Status: ACTIVE

Important: Save the voiceChannelId - you'll need it to create the deployment.

Step 3: Create Voice Deployment​

import { DeploymentStatus, DeploymentProvisioningType } from 'wiil-core-js';

const deployment = await client.deploymentConfigs.create({
  projectId: 'YOUR_PROJECT_ID',
  deploymentChannelId: phoneConfig.voiceChannelId, // ← Use voice channel ID
  agentConfigurationId: 'YOUR_AGENT_ID',
  instructionConfigurationId: 'YOUR_INSTRUCTION_ID',
  deploymentName: 'Voice Support Agent',
  isActive: true,
  deploymentStatus: DeploymentStatus.PENDING,
  provisioningType: DeploymentProvisioningType.DIRECT
});

console.log('✓ Voice deployment created!');
console.log(`Deployment ID: ${deployment.id}`);
console.log(`Call ${phoneConfig.phoneNumber} to test`);

Step 4: Test Your Voice Agent​

Call the phone number to test your AI agent:

📞 Dial: +12125551234

Your AI agent will answer and handle the conversation!

Retrieving Voice Channel Details​

Get Channel by ID​

const voiceChannel = await client.deploymentChannels.get(phoneConfig.voiceChannelId);

console.log('Voice Channel Details:');
console.log(`  Name: ${voiceChannel.channelName}`);
console.log(`  Type: ${voiceChannel.deploymentType}`); // "CALLS"
console.log(`  Phone: ${voiceChannel.channelIdentifier}`);
console.log(`  Recording: ${voiceChannel.recordingEnabled}`);

Get Channel by Phone Number​

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

const voiceChannel = await client.deploymentChannels.getByIdentifier(
  '+12125551234',
  DeploymentType.CALLS
);

console.log(`Voice Channel ID: ${voiceChannel.id}`);

Complete Example​

import { WiilClient } from 'wiil-js';
import { DeploymentStatus, DeploymentProvisioningType } from 'wiil-core-js';

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

  // 1. Purchase phone number
  console.log('1. Purchasing phone number...');
  const purchase = await client.telephonyProvider.purchase({
    phoneNumber: '+12125551234',
    friendlyName: 'Customer Support Line'
  });

  console.log(`Purchase ID: ${purchase.id}`);

  // 2. Wait for completion
  console.log('2. Waiting for purchase to complete (under 5 minutes)...');
  let phoneConfig;
  let attempts = 0;
  const maxAttempts = 60;

  while (attempts < maxAttempts) {
    try {
      phoneConfig = await client.phoneConfigs.getByPhoneNumber('+12125551234');
      if (phoneConfig.status === 'ACTIVE') {
        console.log('✓ Phone purchase completed!');
        break;
      }
    } catch (error) {
      // Phone config not ready yet
    }

    await new Promise(resolve => setTimeout(resolve, 5000));
    attempts++;
  }

  if (!phoneConfig || phoneConfig.status !== 'ACTIVE') {
    throw new Error('Phone purchase timeout');
  }

  // 3. Get voice channel ID
  console.log('3. Voice channel auto-created:');
  console.log(`   Voice Channel ID: ${phoneConfig.voiceChannelId}`);

  // 4. Create deployment
  console.log('4. Creating voice deployment...');
  const deployment = await client.deploymentConfigs.create({
    projectId: 'YOUR_PROJECT_ID',
    deploymentChannelId: phoneConfig.voiceChannelId,
    agentConfigurationId: 'YOUR_AGENT_ID',
    instructionConfigurationId: 'YOUR_INSTRUCTION_ID',
    deploymentName: 'Voice Support Agent',
    isActive: true,
    deploymentStatus: DeploymentStatus.PENDING,
    provisioningType: DeploymentProvisioningType.DIRECT
  });

  console.log('✓ Setup complete!');
  console.log(`\nYour voice agent is ready!`);
  console.log(`📞 Call: ${phoneConfig.phoneNumber}`);
  console.log(`📋 Deployment ID: ${deployment.id}`);

  return { phoneConfig, deployment };
}

setupVoiceChannel().catch(console.error);

Multi-Language Voice Support​

Configure your agent to support multiple languages:

// In your Agent Configuration
const agentConfig = await client.agentConfigs.create({
  agentName: 'Sofia',
  voiceId: 'shimmer', // Supports multiple languages
  language: 'en-US', // Default language
  // Agent will auto-detect and respond in caller's language
});

Supported Languages:

  • English (US, UK, AU)
  • Spanish (ES, MX)
  • French (FR, CA)
  • German (DE)
  • Italian (IT)
  • Portuguese (BR, PT)
  • And more...

Recording Configuration​

Enable Recording​

const updatedChannel = await client.deploymentChannels.update({
  id: phoneConfig.voiceChannelId,
  recordingEnabled: true
});

Disable Recording​

const updatedChannel = await client.deploymentChannels.update({
  id: phoneConfig.voiceChannelId,
  recordingEnabled: false
});

Note: Recordings are stored securely and accessible via WIIL Console.

Voice-Specific Settings​

Agent Voice Selection​

Choose from available voices in your Agent Configuration:

const agentConfig = await client.agentConfigs.create({
  agentName: 'Rachel',
  voiceId: 'alloy',    // Options: alloy, echo, fable, onyx, nova, shimmer
  language: 'en-US'
});

Troubleshooting​

Calls not connecting​

  1. ✅ Verify phone purchase completed (status: ACTIVE)
  2. ✅ Check deployment is active (isActive: true)
  3. ✅ Ensure voiceChannelId is correct
  4. ✅ Verify phone number has voice capability enabled
  5. ✅ Check account has sufficient credits

Agent not responding​

  1. ✅ Verify Agent Configuration is valid
  2. ✅ Check Instruction Configuration exists
  3. ✅ Review agent logs in WIIL Console
  4. ✅ Test with simple instructions first

Recording not available​

  1. ✅ Verify recordingEnabled: true
  2. ✅ Wait a few minutes for processing
  3. ✅ Check WIIL Console recordings section
  4. ✅ Verify call completed successfully

Next Steps​