Skip to main content

SMS Channels Guide

Set up AI-powered text messaging on your phone number

Setup Time: ~5 minutes (including phone purchase)

Overview​

SMS channels enable AI agents to handle text messages. They are automatically created when you purchase a phone number.

Prerequisites​

Before setting up SMS 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​

SMS 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 SMS' // Optional
});

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

Step 2: Get SMS Channel ID​

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

// 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 smsChannelId - you'll need it to create the deployment.

Step 3: Create SMS Deployment​

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

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

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

Step 4: Test Your SMS Agent​

Send a text message to test your AI agent:

📱 Text to: +12125551234
Message: "Hello! I need help with my order."

Your AI agent will respond via SMS!

Retrieving SMS Channel Details​

Get Channel by ID​

const smsChannel = await client.deploymentChannels.get(phoneConfig.smsChannelId);

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

Get Channel by Phone Number​

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

const smsChannel = await client.deploymentChannels.getByIdentifier(
  '+12125551234',
  DeploymentType.SMS
);

console.log(`SMS Channel ID: ${smsChannel.id}`);

Complete Example​

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

async function setupSMSChannel() {
  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 SMS'
  });

  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 SMS channel ID
  console.log('3. SMS channel auto-created:');
  console.log(`   SMS Channel ID: ${phoneConfig.smsChannelId}`);

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

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

  return { phoneConfig, deployment };
}

setupSMSChannel().catch(console.error);

Message Length Handling​

Standard SMS (160 characters)​

Single SMS message supports up to 160 characters.

Long Messages (Concatenated SMS)​

Messages longer than 160 characters are automatically split and reassembled:

  • Split into segments of 153 characters
  • Delivered as single message to recipient
  • Charged per segment

Example:

  • 200 characters = 2 segments = 2 SMS charges
  • 320 characters = 3 segments = 3 SMS charges

Agent Configuration for SMS​

Optimize your agent for concise SMS responses:

const agentConfig = await client.agentConfigs.create({
  agentName: 'Jordan',
  temperature: 0.7,
  maxTokens: 150, // Keep responses under 160 characters
  // Configure agent to be concise
});

Best Practice: Configure instructions to keep responses under 160 characters for cost optimization.

Multi-Language SMS Support​

Configure your agent to support multiple languages:

// In your Agent Configuration
const agentConfig = await client.agentConfigs.create({
  agentName: 'Luna',
  language: 'en-US', // Default language
  // Agent will auto-detect and respond in sender's language
});

Supported Languages:

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

Note: Character encoding may affect message length for non-English languages.

Compliance and Regulations​

US Regulations​

10DLC Registration Required:

  • Local numbers (non-toll-free) require 10DLC registration
  • Registration is automatic for verified businesses
  • Unregistered numbers have lower throughput

A2P Trust Score:

  • Affects message delivery rates
  • Based on: business verification, message content, user engagement
  • Higher scores = better deliverability

TCPA Compliance​

Ensure compliance with Telephone Consumer Protection Act:

  1. ✅ Obtain explicit opt-in consent
  2. ✅ Provide clear opt-out instructions
  3. ✅ Honor opt-out requests immediately
  4. ✅ Keep consent records

Opt-Out Example:

"Reply STOP to unsubscribe"

GDPR Compliance (EU)​

For European customers:

  1. ✅ Obtain clear consent
  2. ✅ Provide data access rights
  3. ✅ Allow data deletion
  4. ✅ Secure data storage

Toll-Free SMS​

Use toll-free numbers for verified business messaging.

Purchase Toll-Free Number​

const phonePurchase = await client.telephonyProvider.purchase({
  phoneNumber: '+18005551234',
  friendlyName: 'Business SMS Line'
});

Benefits:

  • Higher throughput (3 msg/sec vs 1 msg/sec)
  • Better for high-volume messaging
  • Professional appearance
  • No 10DLC registration needed

Verification Required:

  • Toll-free verification through carrier
  • Submit business info and use case
  • Processing time: 5-10 business days

Troubleshooting​

Messages not delivering​

  1. ✅ Verify phone purchase completed (status: ACTIVE)
  2. ✅ Check deployment is active (isActive: true)
  3. ✅ Ensure smsChannelId is correct
  4. ✅ Verify phone number has SMS capability enabled
  5. ✅ Check account has sufficient credits
  6. ✅ Review carrier filtering (spam detection)

Delayed message delivery​

  1. ✅ Check carrier throughput limits
  2. ✅ Verify 10DLC registration status
  3. ✅ Review A2P trust score
  4. ✅ Contact support for carrier status

Agent not responding​

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

Messages marked as spam​

  1. ✅ Complete 10DLC registration
  2. ✅ Improve A2P trust score
  3. ✅ Avoid spam trigger words
  4. ✅ Include opt-out instructions
  5. ✅ Monitor user engagement

Next Steps​