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.
To set up inbound calls, you need to:
Here's how to configure a phone number for inbound calls:
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();
You can monitor inbound calls in real-time and retrieve information about past calls:
// List recent inbound callsconst calls = await pinecall.calls.list({ direction: 'inbound', limit: 10});
console.log(`Found ${calls.length} recent inbound calls`);
// Get details for a specific callconst callId = calls[0].id;const callDetails = await pinecall.calls.get(callId);
console.log('Call details:', callDetails);
// Get transcription for a callconst transcription = await pinecall.calls.getTranscription(callId);
console.log('Call transcription:', transcription);
// Get recording for a callconst recording = await pinecall.calls.getRecording(callId);
console.log('Recording URL:', recording.url);
You can receive real-time notifications about inbound calls by setting up webhooks:
// Set up webhooks for call eventsconst 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:
// Example Express.js webhook handlerconst express = require('express');const crypto = require('crypto');const app = express();
app.use(express.json());
// Verify webhook signaturefunction 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');});
When all your agents are busy, incoming calls can be placed in a queue with customizable wait messages and music.
Configure operating hours for your phone numbers with different handling for calls outside those hours.
Create multi-level menus to route callers based on their selections ("Press 1 for sales, 2 for support...").
Allow your AI agent to transfer calls to human representatives when needed.
Now that you understand inbound calls, you might want to explore: