Inbound Calls

Inbound calls are phone calls initiated by users to your Pinecall phone numbers. When a user calls your number, Pinecall connects them to your configured AI agent, which handles the conversation.

Setting Up Inbound Calls

To set up inbound calls, you need to:

  1. Create an AI agent to handle the conversations
  2. Acquire a phone number from Pinecall
  3. Configure the phone number to connect to your agent

Here's how to configure a phone number for inbound calls:

configure-inbound.js
import { Pinecall } from '@pinecall/sdk';
const pinecall = new Pinecall({
apiKey: process.env.PINECALL_API_KEY
});
async function configureInboundNumber() {
// Replace with your actual phone number ID and agent ID
const phoneNumberId = 'pn_12345';
const agentId = 'agent_67890';
// Configure the phone number
const updatedNumber = await pinecall.phoneNumbers.update(phoneNumberId, {
agentId: agentId,
inboundCallSettings: {
greetingMessage: "Hello! Thank you for calling Acme Inc. How can I help you today?",
recordCalls: true,
transcribeCalls: true,
maxDuration: 900, // 15 minutes in seconds
fallbackNumber: "+15551234567" // Optional: calls will be forwarded here if the agent fails
}
});
console.log(`Phone number ${updatedNumber.number} configured for inbound calls`);
return updatedNumber;
}
configureInboundNumber();

Inbound Call Flow

Here's what happens during an inbound call:

  1. User dials your Pinecall phone number
  2. Pinecall answers the call and establishes a connection
  3. Your configured AI agent is initialized with your provided prompt
  4. The greeting message is played to the caller (if configured)
  5. The caller speaks, and their speech is converted to text
  6. The text is sent to your AI agent for processing
  7. The agent generates a response based on your prompt and the caller's input
  8. The response is converted to speech and played to the caller
  9. This conversation loop continues until the call ends
  10. Call recordings and transcriptions are saved (if enabled)

Monitoring Inbound Calls

You can monitor inbound calls in real-time and retrieve information about past calls:

monitor-calls.js
// List recent inbound calls
const calls = await pinecall.calls.list({
direction: 'inbound',
limit: 10
});
console.log(`Found ${calls.length} recent inbound calls`);
// Get details for a specific call
const callId = calls[0].id;
const callDetails = await pinecall.calls.get(callId);
console.log('Call details:', callDetails);
// Get transcription for a call
const transcription = await pinecall.calls.getTranscription(callId);
console.log('Call transcription:', transcription);
// Get recording for a call
const recording = await pinecall.calls.getRecording(callId);
console.log('Recording URL:', recording.url);

Call Events and Webhooks

You can receive real-time notifications about inbound calls by setting up webhooks:

call-webhooks.js
// Set up webhooks for call events
const webhook = await pinecall.webhooks.create({
url: 'https://your-server.com/webhooks/pinecall',
events: [
'call.started',
'call.ended',
'recording.available',
'transcription.completed'
],
secret: 'your_webhook_secret' // Used to verify webhook authenticity
});
console.log(`Webhook created with ID: ${webhook.id}`);

Here's an example of handling webhook events for inbound calls:

webhook-handler.js
// Example Express.js webhook handler
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());
// Verify webhook signature
function verifyWebhook(req, secret) {
const signature = req.headers['x-pinecall-signature'];
const payload = JSON.stringify(req.body);
const hmac = crypto.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return signature === hmac;
}
app.post('/webhooks/pinecall', (req, res) => {
// Verify webhook signature
if (!verifyWebhook(req, 'your_webhook_secret')) {
return res.status(401).send('Invalid signature');
}
const event = req.body;
// Handle different event types
switch (event.type) {
case 'call.started':
console.log(`Inbound call started: ${event.data.call_id}`);
// Update your UI, database, etc.
break;
case 'call.ended':
console.log(`Call ended: ${event.data.call_id}`);
console.log(`Duration: ${event.data.duration} seconds`);
// Update call records, trigger follow-up actions, etc.
break;
case 'recording.available':
console.log(`Recording available: ${event.data.recording_url}`);
// Download or process the recording
break;
case 'transcription.completed':
console.log(`Transcription completed for call: ${event.data.call_id}`);
// Process the transcription data
break;
}
// Acknowledge receipt of the webhook
res.status(200).send('Webhook received');
});
app.listen(3000, () => {
console.log('Webhook server running on port 3000');
});

Advanced Inbound Call Features

Call Queueing

When all your agents are busy, incoming calls can be placed in a queue with customizable wait messages and music.

Business Hours

Configure operating hours for your phone numbers with different handling for calls outside those hours.

Interactive Voice Response (IVR)

Create multi-level menus to route callers based on their selections ("Press 1 for sales, 2 for support...").

Human Escalation

Allow your AI agent to transfer calls to human representatives when needed.

Best Practices for Inbound Calls

  • Craft clear greeting messages - Make callers feel welcome and set expectations for the AI interaction.
  • Design robust agent prompts - Include instructions for handling common inbound call scenarios.
  • Always enable call recording - Recordings are invaluable for improving your agents and troubleshooting issues.
  • Set up fallback options - Configure human escalation or voicemail for when the AI can't handle a call.
  • Analyze call transcriptions - Regularly review transcripts to find improvement opportunities.

Next Steps

Now that you understand inbound calls, you might want to explore: