Quick Start Guide

This quick start guide will help you create your first voice AI agent, set up a phone number, and make a test call in just a few minutes.

Prerequisites:

  • A Pinecall account (sign up here if you don't have one)
  • Your API key from the Pinecall dashboard
  • Node.js installed (version 14 or higher)

Step 1: Install the SDK

First, create a new project and install the Pinecall SDK:

terminal
# Create a new directory
mkdir pinecall-quickstart
cd pinecall-quickstart


# Initialize a new Node.js project
npm init -y


# Install the Pinecall SDK
npm install @pinecall/sdk dotenv

Create a .env file in your project root to store your API key:

.env
PINECALL_API_KEY=your_api_key_here

Step 2: Create an AI Agent

Create a file named create-agent.js with the following code:

create-agent.js
require('dotenv').config();
const { Pinecall } = require('@pinecall/sdk');


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


async function createAgent() {
  try {
    // Create a customer support agent
    const agent = await pinecall.agents.create({
      name: 'My First Agent',
      voice: 'sophia',
      language: 'en-US',
      prompt: `You are a helpful customer support agent for Acme Inc.
               
               Be friendly and concise in your responses.
               You specialize in answering frequently asked questions 
               about Acme's products and services.
               If asked about specific customer information, politely 
               explain that you don't have access to individual account details.`
    
    console.log(`Agent created successfully with ID: ${agent.id}`);
    console.log(`Make note of this agent ID: ${agent.id}`);
    return agent;
  } catch (error) {
    console.error('Error creating agent:', error.message);
  }
}


// Run the function
createAgent();

Run the script to create your agent:

terminal
node create-agent.js

Important

Make note of the agent ID that is output. You'll need it in the next step.

Step 3: Acquire a Phone Number

Create a file named acquire-number.js with the following code:

acquire-number.js
require('dotenv').config();
const { Pinecall } = require('@pinecall/sdk');


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


// Replace with your agent ID from step 2
const AGENT_ID = 'your_agent_id_here';


async function acquirePhoneNumber() {
  try {
    // Find available phone numbers in the US
    const availableNumbers = await pinecall.phoneNumbers.list({
      country: 'US',
      type: 'local'
    });
    
    if (availableNumbers.length === 0) {
      console.log('No available phone numbers found');
      return;
    }
    
    console.log(`Found ${availableNumbers.length} available numbers`);
    
    // Acquire the first available number
    const phoneNumber = await pinecall.phoneNumbers.acquire({
      phoneNumber: availableNumbers[0].number
    });
    
    console.log(`Acquired phone number: ${phoneNumber.number}`);
    
    // Configure the phone number to use our agent
    const updatedNumber = await pinecall.phoneNumbers.update(phoneNumber.id, {
      friendlyName: 'My First Phone Number',
      agentId: AGENT_ID
    });
    
    console.log(`Phone number configured successfully!`);
    console.log(`You can now call ${updatedNumber.number} to talk to your agent.`);
  } catch (error) {
    console.error('Error:', error.message);
  }
}


// Run the function
acquirePhoneNumber();

Update the AGENT_ID variable with your agent ID from step 2, then run the script:

terminal
node acquire-number.js

Step 4: Test Your Agent

Now you can call the phone number you acquired to interact with your AI agent. Use your mobile phone or any phone to dial the number.

Test Conversation

Try asking your agent some of these questions:

  • "What does Acme Inc. do?"
  • "What are your business hours?"
  • "How can I return a product?"
  • "Tell me about your support options."

Step 5: Make an Outbound Call (Optional)

You can also use your agent to make outbound calls. Create a file named make-call.js with the following code:

make-call.js
require('dotenv').config();
const { Pinecall } = require('@pinecall/sdk');


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


// Replace with your agent ID from step 2
const AGENT_ID = 'your_agent_id_here';


// Replace with your phone number that will receive the call
const YOUR_PHONE_NUMBER = '+15551234567';


async function makeOutboundCall() {
  try {
    // Initiate an outbound call
    // Initiate an outbound call
    const call = await pinecall.calls.create({
      agentId: AGENT_ID,
      to: YOUR_PHONE_NUMBER,
      from: null,  // Will use one of your Pinecall numbers automatically
      initialMessage: `Hello, this is Acme customer support calling. 
                       I'm checking in to see if you need any assistance today.`
    });
    
    console.log(`Call initiated with ID: ${call.id}`);
    console.log(`You should receive a call shortly on ${YOUR_PHONE_NUMBER}`);
  } catch (error) {
    console.error('Error making call:', error.message);
  }
}


// Run the function
makeOutboundCall();

Update the AGENT_ID variable with your agent ID and YOUR_PHONE_NUMBER with your phone number, then run the script:

terminal
node make-call.js

Next Steps

Congratulations! You've created your first voice AI agent and set up a phone number. Here's what you can do next: