Phone Numbers

Phone numbers are the gateway for users to interact with your voice AI agents through traditional phone calls. Pinecall makes it easy to acquire, configure, and manage phone numbers across multiple countries.

Acquiring a Phone Number

You can acquire new phone numbers programmatically using our SDK or through the Pinecall dashboard.

acquire-number.js
import { Pinecall } from '@pinecall/sdk';


const pinecall = new Pinecall({
  apiKey: process.env.PINECALL_API_KEY
});


async function acquirePhoneNumber() {
  // List available phone numbers in the US
  const availableNumbers = await pinecall.phoneNumbers.list({
    country: 'US',
    type: 'local',     // 'local' or 'toll-free'
    areaCode: '415'    // Optional: specify area code
  });
  
  console.log(`Found ${availableNumbers.length} available numbers`);
  
  // Acquire the first available number
  if (availableNumbers.length > 0) {
    const phoneNumber = await pinecall.phoneNumbers.acquire({
      phoneNumber: availableNumbers[0].number
    });
    
    console.log(`Acquired phone number: ${phoneNumber.number}`);
    return phoneNumber;
  }
}

Configuring a Phone Number

After acquiring a phone number, you need to configure it by assigning it to an agent and setting up call handling preferences.

configure-number.js
// Configure a phone number and assign it to an agent
async function configurePhoneNumber(phoneNumberId, agentId) {
  const updatedNumber = await pinecall.phoneNumbers.update(phoneNumberId, {
    agentId: agentId,                   // The agent that will handle calls
    callHandling: {
      voicemail: {
        enabled: true,                  // Enable voicemail when agent is unavailable
        transcribe: true                // Transcribe voicemail messages
      },
      operating_hours: {
        timezone: 'America/Los_Angeles',
        schedule: [
          { day: 'monday', start: '09:00', end: '17:00' },
          { day: 'tuesday', start: '09:00', end: '17:00' },
          { day: 'wednesday', start: '09:00', end: '17:00' },
          { day: 'thursday', start: '09:00', end: '17:00' },
          { day: 'friday', start: '09:00', end: '17:00' }
        ]
      }
    }
  });
  
  console.log(`Phone number ${updatedNumber.number} configured successfully`);
  return updatedNumber;
}

Managing Phone Numbers

Pinecall provides several methods to help you manage your phone numbers:

manage-numbers.js
// List all your phone numbers
const numbers = await pinecall.phoneNumbers.list();


// Get details for a specific phone number
const number = await pinecall.phoneNumbers.get('pn_12345');


// Update a phone number configuration
const updatedNumber = await pinecall.phoneNumbers.update('pn_12345', {
  friendlyName: 'Customer Support Line',
  agentId: 'agent_67890'
});


// Release a phone number you no longer need
await pinecall.phoneNumbers.release('pn_12345');

Number Types and Availability

TypeDescriptionUse Case
LocalNumbers with specific area codesLocal businesses, regional services
Toll-FreeNumbers that are free for callers (800, 888, etc.)Customer support, national services
MobileMobile phone numbers in select countriesSMS-enabled services, personal assistants
InternationalNumbers from various countries worldwideGlobal businesses, international support

Number Availability

Phone number availability varies by country and region. Pinecall currently supports phone numbers in the following regions:

  • United States
  • Canada
  • United Kingdom
  • Australia
  • Germany
  • France
  • Spain
  • Italy
  • Mexico
  • Brazil
  • Japan
  • Singapore
  • And more...

Contact us for specific country availability not listed here.

Best Practices

  • Test your configuration - Always test your phone number setup with real calls before going live.
  • Configure operating hours - Set up appropriate business hours and timezone to manage expectations.
  • Enable voicemail - Always provide a fallback for when your agent can't take calls.
  • Use descriptive names - Give your phone numbers meaningful friendly names for easier management.
  • Monitor call volumes - Keep an eye on your phone number usage to ensure optimal performance.

Forwarding and Call Routing

Pinecall offers advanced call routing capabilities to ensure calls are handled appropriately:

Human Escalation

Configure your agent to forward calls to human operators when certain conditions are met.

Round Robin

Distribute calls across multiple agents to balance workload and specialization.

Conditional Routing

Route calls based on caller information, time of day, or other custom criteria.

Call Queuing

Place callers in a queue with customizable wait messages when all agents are busy.

call-routing.js
// Configure advanced call routing
await pinecall.phoneNumbers.update('pn_12345', {
  callHandling: {
    routing: {
      type: 'conditional',
      conditions: [
        {
          // During business hours, route to primary agent
          condition: 'during_business_hours',
          agentId: 'agent_primary'
        },
        {
          // For VIP callers, route to premium agent
          condition: 'caller_in_group:vip',
          agentId: 'agent_premium'
        },
        {
          // Default fallback agent
          agentId: 'agent_after_hours'
        }
      ],
      // Enable human escalation
      humanEscalation: {
        enabled: true,
        forwardTo: '+15551234567',
        escalationTriggers: ['user_request', 'agent_recommendation']
      }
    }
  }
});

Next Steps

Now that you understand how to manage phone numbers, you can: