# RevCent MCP Operation: `GetAIVoiceCalls`

This document explains how MCP/AI clients should use the `GetAIVoiceCalls` operation in RevCent.

`GetAIVoiceCalls` retrieves a paginated list of previously created AI Voice Calls.

Before working with AI Voice Calls, MCP/AI should read these overviews:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceCall.md
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md
```

The AI Voice Call overview explains how AI Voice Calls are created and how they can be analyzed.

The AI Voice Agent overview explains how AI Voice Agents work as a whole, including inbound agents, outbound agents, triggers, instructions, system actions, Functions, snippets, limits, delays, and customer-experience design.

Sources:
- RevCent operation schema for `GetAIVoiceCalls`
- RevCent operation schema for `GetAIVoiceCall`
- RevCent operation schema guidance for `BigQueryRunQuery`
- AI Voice Call overview: `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceCall.md`
- AI Voice Agent overview: `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md`

---

## Operation Summary

`GetAIVoiceCalls` returns a paginated list of AI Voice Calls.

Use it only when the user needs a small, filtered, paginated set of call records.

Use this operation when:

```text
The user wants recent AI Voice Calls in a date range.
The user wants a small page of calls.
The user wants calls for one or more AI Voice Agents.
The user wants calls filtered by status.
MCP/AI needs to find an AI Voice Call ID before using GetAIVoiceCall.
```

Do not use this operation for reporting, metrics, data mining, aggregations, or bulk retrieval.

---

# Reporting / Metrics / Data Mining Prohibition

Important:

```text
Using GetAIVoiceCalls for reporting, metrics, aggregations, data mining, bulk retrieval, document property search, or dashboard-style analysis is prohibited.
```

Use:

```text
BigQueryRunQuery
```

instead.

This includes questions like:

```text
How many AI Voice Calls happened?
How many calls completed?
What is the no-answer rate?
What is the voicemail rate?
What is the average call duration?
Which AI Voice Agent performs best?
How many calls transferred?
Which calls attempted payment?
Which calls created sales or refunds?
How much revenue did AI Voice Agents recover?
How many API actions did voice agents perform?
```

For those, use `BigQueryRunQuery` against tables such as:

```text
revcent.user.ai_voice_call
revcent.user.ai_voice_agent
revcent.user.api_call
```

and revenue-related tables when needed.

---

# Required Inputs

| Field | Type | Required | Description |
|---|---:|---:|---|
| `date_start` | integer | Yes | Date range start as Unix timestamp in seconds. |
| `date_end` | integer | Yes | Date range end as Unix timestamp in seconds. |
| `limit` | integer | Yes | Number of objects to return. Range: 1 to 25. Default: 25. |
| `page` | integer | Yes | Page number for pagination. |

Example request:

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1
}
```

---

# Optional Filters

`GetAIVoiceCalls` supports optional filters.

| Filter | Type | Description |
|---|---:|---|
| `ai_voice_agent_filter` | array<string> | Filter calls based on one or more associated AI Voice Agent IDs. |
| `status_filter` | array<string> | Filter calls based on call status. |

Example:

```json
{
  "date_start": 1770000000,
  "date_end": 1770086400,
  "limit": 25,
  "page": 1,
  "ai_voice_agent_filter": [
    "YYYYYYYYYYYYYYYYYYYY"
  ],
  "status_filter": [
    "Complete"
  ]
}
```

---

# Pagination

The response includes pagination fields such as:

```text
current_count
current_page
total_count
total_pages
results
```

Important:

```text
Pagination does not make this operation appropriate for data mining or reports.
```

Even though `total_count` may appear in the response, MCP/AI should not use repeated pagination through `GetAIVoiceCalls` to build reports or dashboards.

Use `BigQueryRunQuery` for metrics and analysis.

---

# Result Fields

Each result can include fields such as:

| Field | Meaning |
|---|---|
| `id` | AI Voice Call ID. |
| `created_date_unix` | When the call record was created. |
| `updated_date_unix` | When the call record was last updated. |
| `ai_model` | AI model associated with the call. |
| `ai_source` | AI source/provider associated with the call. |
| `ai_source_session_id` | AI provider session ID. |
| `call_duration_ms` | Total call duration in milliseconds. |
| `call_method` | `inbound` or `outbound`. |
| `call_source` | Voice provider/source. |
| `call_source_account_id` | Voice provider account ID. |
| `call_source_call_id` | Voice provider call ID. |
| `call_source_number` | Voice provider number. |
| `call_source_session_id` | Voice provider session ID. |
| `from` | Call From number. |
| `to` | Call To number. |
| `customer` | Associated customer details, if available. |
| `source_type` | Usually `item` when associated with an item. |
| `item_type` | Associated item type. |
| `item_id` | Associated item ID. |
| `status` | Current call status. |
| `trigger` | Information about what created the call. |
| `third_party_integration_ai` | AI provider integration used. |
| `third_party_integration_voice` | Voice provider integration used. |

Use `GetAIVoiceCall` if the user needs full detail for one specific call.

---

# AI Voice Call Creation Context

AI Voice Calls are created when inbound or outbound AI Voice Agent activity occurs.

Creation paths include:

```text
Inbound call to an inbound AI Voice Agent.
Outbound account-event trigger.
Outbound on-demand/API trigger using TriggerAIVoiceAgent.
```

The `trigger` object can identify the source:

```text
api
account_event
inbound_call
```

If the source is `account_event`, the result may include:

```text
trigger.notation
```

which identifies the event notation that caused the call.

---

# Associated Item Types

Calls may be associated with an item.

Supported `item_type` values include:

```text
sale
customer
product_sale
shipping
subscription
subscription_renewal
salvage_transaction
transaction
chargeback
fraud_detection
```

This allows calls to be tied to ecommerce workflows such as:

```text
Declined sale recovery.
Pending checkout recovery.
Subscription renewal recovery.
Shipping support.
Chargeback prevention.
Fraud verification.
Customer service.
```

---

# GetAIVoiceCalls vs GetAIVoiceCall vs BigQueryRunQuery

| Goal | Use |
|---|---|
| Retrieve one known call by ID | `GetAIVoiceCall` |
| Retrieve a small page of calls | `GetAIVoiceCalls` |
| Find a call ID by date/agent/status | `GetAIVoiceCalls` |
| Count calls | `BigQueryRunQuery` |
| Report calls by day/agent/status | `BigQueryRunQuery` |
| Analyze average duration | `BigQueryRunQuery` |
| Analyze no-answer/voicemail/error rates | `BigQueryRunQuery` |
| Analyze API actions performed during calls | `BigQueryRunQuery` |
| Analyze payment attempts or refunds during calls | `BigQueryRunQuery` |
| Analyze revenue performance | `BigQueryRunQuery` |
| Bulk analysis or data mining | `BigQueryRunQuery` |

---

# Correct BigQuery Use for Metrics

Use the AI Voice Call table:

```sql
`revcent.user.ai_voice_call`
```

Use the AI Voice Agent table:

```sql
`revcent.user.ai_voice_agent`
```

Use the API Call table for system actions and payment/refund/sale-related operations:

```sql
`revcent.user.api_call`
```

Useful relationships:

```text
ai_voice_call.ai_voice_agent → ai_voice_agent.id
api_call.ai_voice_call → ai_voice_call.id
api_call.ai_voice_agent → ai_voice_agent.id
ai_voice_call.sale → sale.id
```

MCP/AI should always call:

```text
GetBigQueryTables
```

before writing production SQL.

---

# Example: Call Counts by AI Voice Agent

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  COUNT(*) AS total_calls,
  SUM(IF(avc.status = 'Completed', 1, 0)) AS completed_calls,
  SUM(IF(avc.status = 'No Answer', 1, 0)) AS no_answer_calls,
  SUM(IF(avc.status = 'Voicemail', 1, 0)) AS voicemail_calls,
  SUM(IF(avc.status = 'Error', 1, 0)) AS error_calls,
  AVG(avc.call_duration) / 1000 AS avg_call_duration_seconds
FROM `revcent.user.ai_voice_call` avc
LEFT JOIN `revcent.user.ai_voice_agent` ava
  ON avc.ai_voice_agent = ava.id
WHERE avc.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY
  ai_voice_agent_id,
  ai_voice_agent_name
ORDER BY total_calls DESC
```

---

# Example: Transfer Rate by AI Voice Agent

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  COUNT(*) AS total_calls,
  SUM(IF(avc.call_transferred, 1, 0)) AS transferred_calls,
  ROUND(SUM(IF(avc.call_transferred, 1, 0)) * 100.0 / COUNT(*), 2) AS transfer_rate_percent
FROM `revcent.user.ai_voice_call` avc
LEFT JOIN `revcent.user.ai_voice_agent` ava
  ON avc.ai_voice_agent = ava.id
WHERE avc.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY
  ai_voice_agent_id,
  ai_voice_agent_name
ORDER BY transfer_rate_percent DESC
```

---

# Example: API/System Actions During AI Voice Calls

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  ac.type AS api_call_type,
  ac.method AS api_call_method,
  COUNT(*) AS api_action_count,
  SUM(IF(ac.code = 1, 1, 0)) AS success_count,
  SUM(IF(ac.code != 1, 1, 0)) AS failure_count
FROM `revcent.user.api_call` ac
JOIN `revcent.user.ai_voice_call` avc
  ON ac.ai_voice_call = avc.id
LEFT JOIN `revcent.user.ai_voice_agent` ava
  ON avc.ai_voice_agent = ava.id
WHERE ac.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY
  ai_voice_agent_id,
  ai_voice_agent_name,
  api_call_type,
  api_call_method
ORDER BY api_action_count DESC
```

---

# Example: Payment Attempt / Refund Action Reporting

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  ac.type AS api_call_type,
  ac.method AS api_call_method,
  COUNT(*) AS payment_or_refund_action_count,
  SUM(IF(ac.code = 1, 1, 0)) AS successful_actions,
  SUM(IF(ac.code != 1, 1, 0)) AS failed_actions,
  ROUND(SUM(IF(ac.code = 1, 1, 0)) * 100.0 / COUNT(*), 2) AS success_rate_percent
FROM `revcent.user.api_call` ac
JOIN `revcent.user.ai_voice_call` avc
  ON ac.ai_voice_call = avc.id
LEFT JOIN `revcent.user.ai_voice_agent` ava
  ON avc.ai_voice_agent = ava.id
WHERE ac.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND REGEXP_CONTAINS(
    LOWER(CONCAT(ac.type, ' ', ac.method)),
    r'sale|payment|transaction|refund|card|pending'
  )
GROUP BY
  ai_voice_agent_id,
  ai_voice_agent_name,
  api_call_type,
  api_call_method
ORDER BY payment_or_refund_action_count DESC
```

MCP/AI should refine this after discovering actual `api_call.type` and `api_call.method` values from the account.

---

# Example: Revenue Performance by AI Voice Agent

This is a schema-dependent starting point.

MCP/AI should confirm the sale table fields with `GetBigQueryTables` before running final SQL.

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  COUNT(DISTINCT avc.id) AS total_calls,
  COUNT(DISTINCT avc.customer) AS unique_customers,
  COUNT(DISTINCT avc.sale) AS related_sales,
  SUM(s.amount) AS related_sale_amount,
  AVG(avc.call_duration) / 1000 AS avg_call_duration_seconds
FROM `revcent.user.ai_voice_call` avc
LEFT JOIN `revcent.user.ai_voice_agent` ava
  ON avc.ai_voice_agent = ava.id
LEFT JOIN `revcent.user.sale` s
  ON avc.sale = s.id
WHERE avc.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY
  ai_voice_agent_id,
  ai_voice_agent_name
ORDER BY related_sale_amount DESC
```

Important:

```text
Replace s.amount if the sale table uses a different confirmed revenue field.
For more accurate attribution, join on sale/transaction/salvage/metadata/notes based on the actual business question.
```

---

# When GetAIVoiceCalls Is Appropriate

Use `GetAIVoiceCalls` for:

```text
Showing a recent page of calls.
Finding an AI Voice Call ID.
Reviewing a few calls manually.
Filtering a small page by AI Voice Agent.
Filtering a small page by status.
```

Example:

```text
Show the most recent 25 AI Voice Calls for this AI Voice Agent.
```

This is a retrieval task, so `GetAIVoiceCalls` is appropriate.

---

# When GetAIVoiceCalls Is Not Appropriate

Do not use `GetAIVoiceCalls` for:

```text
How many calls did we make this month?
What is the average call duration?
Which AI Voice Agent performs best?
How much revenue did voice agents recover?
How many payment attempts succeeded?
How many calls went to voicemail?
What is the transfer rate?
Which campaigns produced the best call outcomes?
Bulk export-like retrieval.
Data mining.
```

Use `BigQueryRunQuery`.

---

# Bulk Export Note

If the user wants a bulk export rather than analytics, refer them to the bulk export utility guide:

```text
https://kb.revcent.com/en/revcent-account/bulk-export
```

Do not try to page through all AI Voice Calls with `GetAIVoiceCalls`.

---

# MCP/AI Decision Guide

User asks:

```text
Show me this call.
```

Use:

```text
GetAIVoiceCall
```

User asks:

```text
Show me recent calls.
```

Use:

```text
GetAIVoiceCalls
```

User asks:

```text
How many calls? What is the rate? What is performance? What is revenue impact?
```

Use:

```text
BigQueryRunQuery
```

---

# Validation Checklist

Before calling `GetAIVoiceCalls`:

1. `date_start` is provided.
2. `date_end` is provided.
3. `limit` is provided and between 1 and 25.
4. `page` is provided.
5. The user is asking for paginated retrieval, not metrics/reporting.
6. Optional `ai_voice_agent_filter` values are valid 20-character AI Voice Agent IDs.
7. Optional `status_filter` values match expected call statuses.
8. If the user asks for counts, metrics, aggregation, or analysis, use `BigQueryRunQuery`.
9. If the user wants a specific call's details, use `GetAIVoiceCall` after identifying the call ID.
10. If the user wants bulk export, refer to the bulk export utility guide.

---

# Common Mistakes

## Mistake: Paginating for Reports

Wrong:

```text
Call GetAIVoiceCalls page by page to calculate total calls by status.
```

Correct:

```text
Use BigQueryRunQuery against revcent.user.ai_voice_call.
```

## Mistake: Treating `total_count` as a Reporting Substitute

Wrong:

```text
Use total_count from GetAIVoiceCalls as a dashboard metric.
```

Correct:

```text
Use BigQueryRunQuery for accurate reporting and metrics.
```

## Mistake: Reporting Revenue Without Joins

Wrong:

```text
Assume call count equals recovered revenue.
```

Correct:

```text
Join ai_voice_call, api_call, sale, transaction, salvage_transaction, metadata, and notes as needed.
```

## Mistake: Ignoring API Calls

Wrong:

```text
Only report call completion and duration.
```

Better:

```text
Also analyze api_call.ai_voice_call and api_call.ai_voice_agent for system actions, payment attempts, refunds, emails, notes, metadata, and Functions.
```

---

# Key Takeaways

```text
GetAIVoiceCalls retrieves a small paginated list of AI Voice Calls.
```

```text
It requires date_start, date_end, limit, and page.
```

```text
It supports filtering by AI Voice Agent ID and status.
```

```text
Using GetAIVoiceCalls for reporting, metrics, aggregations, data mining, bulk retrieval, or dashboards is prohibited.
```

```text
Use BigQueryRunQuery for AI Voice Call reporting, performance metrics, payment attempt reporting, and revenue analysis.
```

```text
MCP/AI should read both AI Voice Call and AI Voice Agent overviews before designing or deeply analyzing voice-call workflows:
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceCall.md
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md
```


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.