> ## Documentation Index
> Fetch the complete documentation index at: https://docs.8call.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Feedback System

> Understand how AI-powered call feedback works in 8call to improve agent performance

The call feedback system provides AI-generated insights and performance scores for every completed call, helping you understand call quality and identify areas for improvement.

## How It Works

After each call ends, our AI system automatically analyzes the conversation transcript and generates:

* **Performance Score** (0-10): Overall call quality rating
* **Written Feedback**: Detailed analysis of call performance
* **Improvement Suggestions**: Specific recommendations for better results

<Note>
  Feedback generation happens in the background and doesn't affect call completion or webhook delivery times.
</Note>

## What Gets Analyzed

The AI evaluates calls based on several key factors:

### Communication Quality

* Professionalism and tone
* Clear articulation and pacing
* Active listening skills
* Appropriate language use

### Effectiveness

* Goal achievement (sales conversion, issue resolution)
* Problem-solving approach
* Information gathering
* Call structure and flow

### Customer Experience

* Empathy and rapport building
* Responsiveness to customer needs
* Handling of objections or concerns
* Overall customer satisfaction indicators

## API Endpoints

### Get Call Feedback

Retrieve feedback for a specific call:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(`/api/call-feedback/${callId}`, {
    headers: {
      'x-user-token': 'your-token-here'
    }
  });

  const { data } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    f'/api/call-feedback/{call_id}',
    headers={'x-user-token': 'your-token-here'}
  )

  data = response.json()['data']
  ```

  ```curl cURL theme={null}
  curl -X GET '/api/call-feedback/{callId}' \
    -H 'x-user-token: your-token-here'
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "id": "feedback_123",
      "call_id": "call_456",
      "score": 8,
      "feedback": "The agent demonstrated excellent professionalism and successfully addressed the customer's concerns. The call flow was well-structured with clear explanations.",
      "improvement_suggestions": "Consider asking more qualifying questions early in the call to better understand customer needs and tailor the presentation accordingly.",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "success": true
  }
  ```
</ResponseExample>

### List Call Feedback

Get feedback for multiple calls with filtering options:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('/api/call-feedback?limit=20&minScore=7', {
    headers: {
      'x-user-token': 'your-token-here'
    }
  });

  const { data } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    '/api/call-feedback',
    params={'limit': 20, 'minScore': 7},
    headers={'x-user-token': 'your-token-here'}
  )

  data = response.json()['data']
  ```

  ```curl cURL theme={null}
  curl -X GET '/api/call-feedback?limit=20&minScore=7' \
    -H 'x-user-token: your-token-here'
  ```
</CodeGroup>

#### Query Parameters

<ParamField query="limit" type="integer" default="50">
  Maximum number of results to return (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip for pagination
</ParamField>

<ParamField query="minScore" type="integer">
  Filter feedback with score greater than or equal to this value (0-10)
</ParamField>

<ParamField query="maxScore" type="integer">
  Filter feedback with score less than or equal to this value (0-10)
</ParamField>

### Get Feedback Statistics

Retrieve aggregate statistics for your organization:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('/api/call-feedback/stats?days=30', {
    headers: {
      'x-user-token': 'your-token-here'
    }
  });

  const { data } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    '/api/call-feedback/stats',
    params={'days': 30},
    headers={'x-user-token': 'your-token-here'}
  )

  stats = response.json()['data']
  ```

  ```curl cURL theme={null}
  curl -X GET '/api/call-feedback/stats?days=30' \
    -H 'x-user-token: your-token-here'
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "averageScore": 7.8,
      "totalFeedback": 150,
      "scoreDistribution": [
        {"score": 0, "count": 0},
        {"score": 1, "count": 1},
        {"score": 2, "count": 2},
        ...
        {"score": 10, "count": 15}
      ]
    },
    "success": true
  }
  ```
</ResponseExample>

## Database Schema

The call feedback is stored in the `call_feedback` table with the following structure:

<Tabs>
  <Tab title="Table Structure">
    ```sql theme={null}
    CREATE TABLE call_feedback (
      id UUID PRIMARY KEY,
      call_id UUID REFERENCES calls(id),
      agent_id UUID REFERENCES agents(id),
      organization_id UUID REFERENCES organizations(id),

      -- Feedback data
      score INTEGER CHECK (score >= 0 AND score <= 10),
      feedback TEXT,
      improvement_suggestions TEXT,

      -- Timestamps
      created_at TIMESTAMPTZ DEFAULT NOW(),
      updated_at TIMESTAMPTZ DEFAULT NOW()
    );
    ```
  </Tab>

  <Tab title="Indexes">
    ```sql theme={null}
    -- Performance indexes
    CREATE INDEX idx_call_feedback_call_id ON call_feedback(call_id);
    CREATE INDEX idx_call_feedback_organization_id ON call_feedback(organization_id);
    CREATE INDEX idx_call_feedback_score ON call_feedback(score);
    ```
  </Tab>
</Tabs>

## Feedback Generation

The feedback system works as follows:

<Steps>
  <Step title="Call Completion">
    When a call ends, the system receives the transcript and call details.
  </Step>

  <Step title="AI Analysis">
    AI analyzes the transcript in the background without blocking other processes.
  </Step>

  <Step title="Feedback Storage">
    Only after successful AI analysis is the feedback record inserted into the database.
  </Step>
</Steps>

## Error Handling

The feedback system is designed to be non-blocking and fault-tolerant:

* **No Impact on Calls**: Feedback generation never affects call completion or webhook delivery
* **Silent Failures**: Failed feedback generation is logged but doesn't create incomplete records
* **Graceful Degradation**: If feedback fails, the call record remains intact and accessible
* **Error Logging**: All errors are captured in Sentry for monitoring and debugging

<Warning>
  Feedback generation requires a valid transcript. Calls without transcripts or with very short durations may not generate feedback.
</Warning>

## Best Practices

### Using Feedback Data

1. **Regular Review**: Check feedback regularly to identify patterns and trends
2. **Agent Training**: Use improvement suggestions for targeted coaching
3. **Performance Tracking**: Monitor average scores over time to measure improvement
4. **Quality Assurance**: Use low-scoring calls for additional review

### API Usage

1. **Pagination**: Use limit and offset for large datasets
2. **Filtering**: Apply score filters to focus on specific performance ranges
3. **Caching**: Cache feedback data appropriately as it doesn't change once created

<Tip>
  Use the statistics endpoint to get overview metrics before diving into individual call feedback for more efficient analysis.
</Tip>

## Troubleshooting

### No Feedback Generated

If feedback isn't appearing for completed calls:

1. **Transcript Availability**: Ensure the call has a valid transcript
2. **Call Duration**: Very short calls (\< 30 seconds) may not generate feedback
3. **System Status**: Check if there are any ongoing system issues
4. **Background Processing**: Feedback generation can take 10-30 seconds after call completion

### Low Quality Feedback

If feedback seems inaccurate or unhelpful:

1. **Transcript Quality**: Poor audio quality can affect transcript accuracy
2. **Call Context**: Ensure calls have sufficient context for AI analysis
3. **Feedback Patterns**: Look for patterns across multiple calls rather than focusing on individual instances

<AccordionGroup>
  <Accordion title="Common Issues">
    * **No feedback appearing**: Check transcript availability and call duration
    * **Missing feedback for old calls**: System only generates feedback for new calls after implementation
    * **Delayed feedback**: AI analysis happens in background and can take 10-30 seconds
  </Accordion>

  <Accordion title="Performance Considerations">
    * Feedback generation typically takes 10-30 seconds per call
    * Processing happens in background without affecting call completion
    * Statistics queries are optimized but may be slower for large datasets
  </Accordion>
</AccordionGroup>