Calls - Feather

What Are Calls?

Calls are records of completed voice interactions between your agents and customers. Each call captures the complete conversation details, outcomes, transcripts, and analytics that help you understand and improve your voice AI performance. Call records provide:

Full transcripts - Complete conversation text
Call recordings - Audio files of conversations
Metadata - Duration, timestamps, phone numbers
Dispositions - Call outcomes and results
Analytics - Performance metrics and insights
Tool usage - Which tools were called during conversation
Lead information - Associated customer data

Call Lifecycle

Call States

Calls progress through these states:

INITIATED → IN_PROGRESS → COMPLETED
                    ↓
                FAILED/CANCELLED

INITIATED - Call is being placed or received
IN_PROGRESS - Active conversation happening
COMPLETED - Call ended normally
FAILED - Call failed to connect or encountered error
CANCELLED - Call was cancelled before completion

Call Flow

Dispatch/Inbound → Call initiated
Connection → Agent answers/customer answers
Conversation → AI interaction with tools
Conclusion → Call ends with disposition
Post-Processing → Transcript, summary, recording saved
Record Available → Call data accessible via API

Retrieving Call Data

List All Calls

Get all calls for your organization:

const response = await fetch('https://prod.featherhq.com/api/v1/calls', {
  headers: {
    'X-API-Key': API_KEY
  }
});

const calls = await response.json();

calls.forEach(call => {
  console.log(`Call ${call.id}: ${call.disposition} - ${call.duration}s`);
});

Get Specific Call

Retrieve detailed information for a single call:

const callId = "call-123";

const response = await fetch(`https://prod.featherhq.com/api/v1/calls/${callId}`, {
  headers: {
    'X-API-Key': API_KEY
  }
});

const call = await response.json();

console.log('Transcript:', call.transcript);
console.log('Recording URL:', call.recordingUrl);
console.log('Duration:', call.duration);
console.log('Disposition:', call.disposition);

Call Record Structure

Basic Call Information

{
  id: "call-abc123",
  agentId: "agent-456",
  agentVersionId: "version-789",
  leadId: "lead-012",

  // Phone numbers
  fromPhoneNumber: "+14155551234",
  toPhoneNumber: "+14155559876",

  // Timing
  startedAt: "2024-01-20T10:30:00Z",
  endedAt: "2024-01-20T10:35:30Z",
  duration: 330, // seconds

  // Outcome
  disposition: "CALENDLY",
  status: "COMPLETED",

  // Direction
  direction: "OUTBOUND" // or "INBOUND"
}

Conversation Data

{
  // Full conversation transcript
  transcript: [
    {
      speaker: "agent",
      text: "Hi, this is Sarah from Feather AI. Is this John?",
      timestamp: "2024-01-20T10:30:05Z"
    },
    {
      speaker: "customer",
      text: "Yes, this is John.",
      timestamp: "2024-01-20T10:30:08Z"
    },
    {
      speaker: "agent",
      text: "Great! I'm calling to follow up on your interest in our Enterprise plan.",
      timestamp: "2024-01-20T10:30:12Z"
    }
  ],

  // Audio recording
  recordingUrl: "https://recordings.featherhq.com/call-abc123.mp3",

  // AI-generated summary
  summary: "Customer confirmed interest in Enterprise plan. Scheduled demo for Wednesday at 2 PM. Budget approved for Q1."
}

Tool Executions

{
  toolCalls: [
    {
      toolId: "calendly-integration",
      toolName: "Schedule Calendly Meeting",
      executedAt: "2024-01-20T10:34:00Z",
      success: true,
      response: {
        meetingUrl: "https://calendly.com/feather/demo-abc123",
        scheduledTime: "2024-01-24T14:00:00Z"
      }
    },
    {
      toolId: "crm-update",
      toolName: "Update CRM Record",
      executedAt: "2024-01-20T10:35:00Z",
      success: true,
      response: {
        updated: true,
        fields: ["status", "next_action", "demo_scheduled"]
      }
    }
  ]
}

Extracted Variables

{
  extractedVariables: {
    customerInterest: "Enterprise plan",
    budget: "Q1 approved",
    timeline: "2-3 months",
    demoScheduled: true,
    nextSteps: "Product demo on Wednesday"
  }
}

Call Dispositions

Dispositions indicate how calls ended:

Disposition	Description	Typical Action
`ENDED`	Normal call completion	Mark as contacted
`CALENDLY`	Appointment booked	Add to calendar follow-up
`NOT_INTERESTED`	Customer declined	Mark as lost, remove from campaign
`WARM_TRANSFER`	Transferred to human	Follow up with transfer notes
`NO_ANSWER`	Customer didn’t answer	Schedule retry
`VOICEMAIL_DETECTED`	Voicemail encountered	Flag for follow-up
`LEFT_VOICEMAIL`	Message left	Wait before retry
`DNC`	Do not call request	Add to DNC list immediately
`CALL_AGAIN`	Requested callback	Schedule specific follow-up
`TEXT_CONSENT`	Agreed to text messaging	Enable SMS in workflow
`BAD_NUMBER`	Invalid/disconnected	Mark as bad data
`LINE_BUSY`	Line was busy	Retry later
`FRAUD`	Suspected fraud	Flag for review
`SILENCE_TIMEOUT`	No response detected	Review call quality
`COULD_NOT_CONNECT`	Connection failed	Check phone number, retry

Filtering and Querying

Filter by Date Range

const startDate = "2024-01-01";
const endDate = "2024-01-31";

const response = await fetch(
  `https://prod.featherhq.com/api/v1/calls?startDate=${startDate}&endDate=${endDate}`,
  {
    headers: { 'X-API-Key': API_KEY }
  }
);

Filter by Agent

const agentId = "agent-123";

const response = await fetch(
  `https://prod.featherhq.com/api/v1/calls?agentId=${agentId}`,
  {
    headers: { 'X-API-Key': API_KEY }
  }
);

Filter by Disposition

const disposition = "CALENDLY";

const response = await fetch(
  `https://prod.featherhq.com/api/v1/calls?disposition=${disposition}`,
  {
    headers: { 'X-API-Key': API_KEY }
  }
);

Call Analytics

Key Metrics to Track

Volume Metrics:

Total calls
Calls per day/week/month
Inbound vs outbound ratio
Peak calling hours

Performance Metrics:

Average call duration
Answer rate (inbound)
Connect rate (outbound)
Disposition distribution

Success Metrics:

Conversion rate (meetings booked, sales made)
Tool usage rate
Transfer rate
Customer satisfaction (from post-call variables)

Quality Metrics:

Transcript quality scores
Tool execution success rate
Error/failure rate
Silence/timeout rate

Calculating Metrics

// Get all calls
const calls = await fetch('https://prod.featherhq.com/api/v1/calls', {
  headers: { 'X-API-Key': API_KEY }
}).then(r => r.json());

// Calculate metrics
const metrics = {
  totalCalls: calls.length,

  avgDuration: calls.reduce((sum, c) => sum + c.duration, 0) / calls.length,

  dispositionBreakdown: calls.reduce((acc, c) => {
    acc[c.disposition] = (acc[c.disposition] || 0) + 1;
    return acc;
  }, {}),

  conversionRate: calls.filter(c => c.disposition === 'CALENDLY').length / calls.length,

  answerRate: calls.filter(c => c.status === 'COMPLETED').length / calls.length
};

console.log(metrics);

Call Recordings

Accessing Recordings

Call recordings are available via URL:

const call = await getCall(callId);
const recordingUrl = call.recordingUrl;

// Download recording
const recording = await fetch(recordingUrl);
const audioBlob = await recording.blob();

// Or use directly in audio player
const audio = new Audio(recordingUrl);
audio.play();

Recording Storage

Format: MP3
Quality: High-quality audio
Retention: Based on your plan (typically 30-90 days)
Access: Presigned URLs with expiration

Transcripts

Transcript Format

Transcripts include:

Speaker identification (agent vs. customer)
Timestamps for each utterance
Full conversation text
Turn-by-turn dialogue

{
  transcript: [
    {
      speaker: "agent",
      text: "Hello, this is the Feather support team. How can I help you today?",
      timestamp: "2024-01-20T10:30:00Z",
      confidence: 0.98
    },
    {
      speaker: "customer",
      text: "I'm having trouble accessing my account.",
      timestamp: "2024-01-20T10:30:05Z",
      confidence: 0.95
    }
  ]
}

Using Transcripts

Quality assurance:

// Review agent performance
const agentMessages = call.transcript.filter(t => t.speaker === 'agent');
const avgConfidence = agentMessages.reduce((sum, m) => sum + m.confidence, 0) / agentMessages.length;

Training data:

// Extract successful conversation patterns
const successfulCalls = calls.filter(c => c.disposition === 'CALENDLY');
const successfulTranscripts = successfulCalls.map(c => c.transcript);

Compliance:

// Check for required disclosures
const hasDisclosure = call.transcript.some(t =>
  t.speaker === 'agent' && t.text.includes('recorded for quality')
);

Post-Call Processing

Automated Actions

Trigger actions based on call outcomes:

// After call completes
if (call.disposition === 'CALENDLY') {
  // Send calendar invite
  await sendCalendarInvite(call.leadId, call.extractedVariables.meetingTime);

  // Update CRM
  await updateCRM(call.leadId, { status: 'demo_scheduled' });

  // Send confirmation email
  await sendEmail(call.leadId, 'meeting-confirmation');
}

if (call.disposition === 'DNC') {
  // Add to DNC list immediately
  await addToDNCList(call.toPhoneNumber);

  // Stop all workflows
  await cancelWorkflows(call.leadId);
}

Call Summaries

Use AI-generated summaries for quick review:

{
  summary: "Customer inquired about Enterprise pricing. Confirmed budget of $50K for Q1. Interested in API integration and SSO features. Scheduled technical demo for next Tuesday at 2 PM.",

  keyPoints: [
    "Budget: $50K approved",
    "Timeline: Q1 implementation",
    "Requirements: API, SSO",
    "Next step: Tech demo scheduled"
  ],

  sentiment: "positive",
  nextAction: "Prepare technical demo materials"
}

Best Practices

Monitoring Calls

Regular review - Check recent calls daily
Quality spot-checking - Listen to random samples
Disposition tracking - Monitor outcome distribution
Duration analysis - Flag unusually short/long calls
Error monitoring - Track failed calls and investigate

Using Call Data

Agent improvement - Identify successful patterns
Training data - Use transcripts to refine prompts
Customer insights - Analyze common questions and objections
Workflow optimization - Adjust based on outcomes
Compliance - Ensure regulatory requirements are met

Data Retention

Archive old calls - Export and store historical data
Compliance requirements - Retain per legal obligations
Privacy policies - Delete data per customer requests
Cost optimization - Balance storage needs with costs
Backup strategy - Keep copies of critical recordings

Common Use Cases

Quality Assurance

Review call quality and agent performance

Training & Improvement

Use successful calls to improve agent prompts

Compliance Monitoring

Ensure calls meet regulatory requirements

Customer Insights

Analyze conversations to understand customer needs

Performance Analytics

Track conversion rates and call metrics

Dispute Resolution

Reference recordings for conflict resolution

Troubleshooting

Missing Recordings

Causes:

Recording not yet processed
Storage limit reached
Recording disabled in agent config
Processing error

Solutions:

Wait for processing (can take 1-2 minutes)
Check agent recording settings
Verify storage quota
Contact support if persistent

Poor Transcript Quality

Causes:

Background noise
Poor connection quality
Multiple speakers talking
Unclear speech

Solutions:

Improve STT configuration
Use noise-canceling settings
Guide customers to quiet environments
Adjust confidence thresholds

Missing Call Data

Verify:

Call completed successfully
Sufficient time has passed for processing
Call ID is correct
API permissions are set

Next Steps

Agents

Configure agents for better call performance

Workflows

Automate follow-ups based on call dispositions

Leads

Use call data to enrich lead profiles

API Reference

Explore the calls API

Getting Started

Core Concepts

​What Are Calls?

​Call Lifecycle

​Call States

​Call Flow

​Retrieving Call Data

​List All Calls

​Get Specific Call

​Call Record Structure

​Basic Call Information

​Conversation Data

​Tool Executions

​Extracted Variables

​Call Dispositions

​Filtering and Querying

​Filter by Date Range

​Filter by Agent

​Filter by Disposition

​Call Analytics

​Key Metrics to Track

​Calculating Metrics

​Call Recordings

​Accessing Recordings

​Recording Storage

​Transcripts

​Transcript Format

​Using Transcripts

​Post-Call Processing

​Automated Actions

​Call Summaries

​Best Practices

​Monitoring Calls

​Using Call Data

​Data Retention

​Common Use Cases