# RevCent AI Voice Calls Overview

This document explains AI Voice Calls in RevCent: what they are, how they are created, how they relate to inbound and outbound AI Voice Agents, how they are useful for ecommerce businesses, and how to use `BigQueryRunQuery` for AI Voice Call metrics and reporting.

This is not a single operation guide. It is an overview of AI Voice Calls as a RevCent system capability.

Sources:
- RevCent operation schema for `GetAIVoiceCall`
- RevCent operation schema for `GetAIVoiceCalls`
- RevCent operation schema for `TriggerAIVoiceAgent`
- RevCent operation schema guidance for `BigQueryRunQuery`
- RevCent BigQuery table schema from `GetBigQueryTables`

---

# What Is an AI Voice Call?

An AI Voice Call is the individual call record created when a RevCent AI Voice Agent handles a phone call.

An AI Voice Call can be created from:

```text
Inbound call
Outbound account-event trigger
Outbound on-demand/API trigger
```

An AI Voice Call records the operational details of the call, including:

```text
AI Voice Call ID
AI Voice Agent ID
Call method: inbound or outbound
Call status
Call duration
From number
To number
Voice provider/source
AI provider/model/source
Associated customer
Associated item type and item ID
Trigger source
Third-party AI integration
Third-party voice integration
Provider call/session IDs
```

The AI Voice Call is the record that lets RevCent users, MCP clients, AI workflows, support teams, and reporting systems understand what happened at the call level.

---

# AI Voice Call vs AI Voice Agent

AI Voice Agents and AI Voice Calls are related, but they are not the same thing.

| Concept | Meaning |
|---|---|
| AI Voice Agent | The configured voice agent: instructions, voice, integrations, triggers, system actions, limits, and active window. |
| AI Voice Call | A single actual call created when an AI Voice Agent handles or initiates a call. |

Analogy:

```text
AI Voice Agent = the configured worker.
AI Voice Call = one job/run handled by that worker.
```

A single AI Voice Agent can create many AI Voice Calls over time.

---

# How AI Voice Calls Are Created

AI Voice Calls are created when an AI Voice Agent is activated by an inbound or outbound call path.

---

## 1. Inbound AI Voice Calls

An inbound AI Voice Call is created when someone calls the phone number connected to an inbound AI Voice Agent.

Conceptual flow:

```text
Customer calls the configured phone number
  ↓
Voice provider receives the call
  ↓
RevCent routes the call to the matching inbound AI Voice Agent
  ↓
RevCent creates an AI Voice Call record
  ↓
RevCent attempts to match the caller to a customer when possible
  ↓
RevCent compiles the AI Voice Agent instructions
  ↓
The AI Voice Agent speaks with the caller in realtime
  ↓
The AI Voice Call record tracks call details and status
```

Inbound calls are useful for:

```text
Customer support
Order lookup
Shipment tracking
Refund questions
Subscription questions
Payment support
Product questions
General ecommerce assistance
After-hours support
```

Inbound AI Voice Calls are created because the caller initiated the interaction.

The `trigger.source` for an inbound-created call can be:

```text
inbound_call
```

---

## 2. Outbound Account-Event AI Voice Calls

An outbound account-event AI Voice Call is created when an outbound AI Voice Agent is triggered by a RevCent account event.

Examples:

```text
sale.created.failed.declined
sale.created.success.pending
subscription_renewal.updated.failed
trial.updated.expired.failed
shipping.updated.delivered
chargeback.created
customer.updated.customer_group.added
```

Conceptual flow:

```text
RevCent account event occurs
  ↓
Outbound AI Voice Agent trigger matches the event
  ↓
Delay period may apply
  ↓
Filters are checked after delay
  ↓
Filter Function must return pass when configured
  ↓
RevCent creates an AI Voice Call
  ↓
RevCent identifies the customer phone number from the item/customer context
  ↓
RevCent initiates the outbound call
  ↓
Pre-agent Function may run
  ↓
Instructions are compiled
  ↓
AI Voice Agent handles the call
```

The `trigger.source` for this type of call can be:

```text
account_event
```

The call may also include:

```text
trigger.notation
```

which identifies the event notation that caused the call.

This is valuable for reporting because businesses can analyze call performance by event type.

---

## 3. Outbound On-Demand / API AI Voice Calls

An outbound on-demand AI Voice Call is created when an on-demand outbound AI Voice Agent is explicitly triggered through the API/MCP or another workflow.

The operation used for this is:

```text
TriggerAIVoiceAgent
```

Important requirements:

```text
The AI Voice Agent must be outbound.
The AI Voice Agent trigger must be on_demand.
The request must include source_type = item.
The request must include item_type and item_id.
The item must be associated with a customer phone number.
```

Conceptual flow:

```text
MCP/API/user decides to trigger an outbound call
  ↓
TriggerAIVoiceAgent is called with ai_voice_agent_id, item_type, and item_id
  ↓
RevCent validates the agent is outbound and on-demand
  ↓
RevCent retrieves the item context
  ↓
RevCent identifies the associated customer and phone number
  ↓
RevCent creates an AI Voice Call
  ↓
RevCent initiates the outbound call
```

The `trigger.source` for an API/on-demand call can be:

```text
api
```

This is useful for:

```text
Manual customer follow-up
Support-triggered outbound calls
External CRM workflows
MCP-driven support workflows
High-value customer outreach
Explicit revenue recovery calls
```

---

# Core AI Voice Call Fields

The `GetAIVoiceCall` operation retrieves the details of one specific AI Voice Call using:

```text
ai_voice_call_id
```

Important fields include:

| Field | Meaning |
|---|---|
| `id` | 20-character 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 triggered the call. |
| `third_party_integration_ai` | AI provider integration used. |
| `third_party_integration_voice` | Voice provider integration used. |

---

# Supported Associated Item Types

AI Voice Calls can 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 is important because the call can be tied back to the business object that caused or contextualized the call.

Examples:

```text
A declined sale recovery call → item_type = sale
A customer support callback → item_type = customer
A shipment issue call → item_type = shipping
A failed subscription renewal call → item_type = subscription_renewal
A chargeback follow-up call → item_type = chargeback
A fraud review call → item_type = fraud_detection
```

---

# AI Voice Call Status

`GetAIVoiceCall` exposes current call status values such as:

```text
Active
Complete
Timer
Cancelled
Error
```

The BigQuery `ai_voice_call` table can include status values such as:

```text
Completed
Error
Active
Cancelled
No Answer
Busy
Voicemail
Robocall
```

MCP/AI should use the status values returned by the relevant operation/table being queried and avoid assuming the operation response status enum exactly matches BigQuery status strings.

Status is useful for:

```text
Completion reporting
Error monitoring
No-answer analysis
Voicemail analysis
Outbound call quality tracking
Robocall classification review
Call retry strategy
```

---

# Trigger Information

AI Voice Calls include trigger information.

The `trigger` object can identify how the call was created.

Trigger source values include:

```text
api
account_event
inbound_call
```

If the trigger source is `account_event`, the call may include:

```text
trigger.notation
```

Example:

```text
sale.created.failed.declined
subscription_renewal.updated.failed
```

If the trigger source is `api`, the call may include API call details.

This is useful for answering questions like:

```text
Was this call triggered by an inbound customer call?
Was this call triggered by an account event?
Was this call triggered by MCP/API?
Which event caused the call?
Which API account initiated the call?
```

---

# AI and Voice Integrations

An AI Voice Call can include both:

```text
third_party_integration_ai
third_party_integration_voice
```

These identify the integrations used during the call.

Conceptually:

```text
third_party_integration_ai = realtime AI model integration
third_party_integration_voice = phone/voice provider integration
```

Examples:

```text
AI integration: OpenAI realtime model
Voice integration: Twilio phone integration
```

This helps with:

```text
Debugging
Provider-specific reporting
Integration auditing
Call quality analysis
Cost/performance comparison
Operational visibility
```

---

# GetAIVoiceCall vs GetAIVoiceCalls

| Goal | Correct Operation |
|---|---|
| Retrieve one known AI Voice Call by ID | `GetAIVoiceCall` |
| Retrieve a small filtered/paginated list of AI Voice Calls | `GetAIVoiceCalls` |
| Count calls | `BigQueryRunQuery` |
| Report call volume by day | `BigQueryRunQuery` |
| Analyze call duration | `BigQueryRunQuery` |
| Report completion/no-answer/voicemail/error rates | `BigQueryRunQuery` |
| Analyze call performance by AI Voice Agent | `BigQueryRunQuery` |
| Analyze transfers | `BigQueryRunQuery` |
| Data mining / metrics / aggregations | `BigQueryRunQuery` |

---

# GetAIVoiceCalls Is Not for Metrics

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

It supports:

```text
date_start
date_end
limit
page
ai_voice_agent_filter
status_filter
```

However, it must not be used for:

```text
Counting
Aggregations
Metrics
Data mining
Bulk retrieval
Document property search
Reporting
```

For those cases, MCP/AI should use:

```text
BigQueryRunQuery
```

This is especially important for AI Voice Call reporting because call metrics often involve counts, rates, averages, grouping, timeframes, and comparisons across many calls.

---

# BigQuery Table for AI Voice Calls

RevCent BigQuery includes the AI Voice Call table:

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

The table contains all AI Voice Calls created.

The BigQuery schema describes an AI Voice Call as being created when an outbound or inbound call occurs and associated with an AI Voice Agent.

Important fields include:

| Field | Meaning |
|---|---|
| `created_at` | Timestamp when the call was created. |
| `id` | AI Voice Call ID. |
| `ai_voice_agent` | Related AI Voice Agent ID. |
| `customer` | Related customer ID, if applicable. |
| `sale` | Related sale ID, if applicable. |
| `call_to` | To number. |
| `call_from` | From number. |
| `call_method` | `outbound` or `inbound`. |
| `source_type` | Usually `item` when item-related. |
| `item_type` | Related item type. |
| `item_id` | Related item ID. |
| `status` | Call status. |
| `call_duration` | Call duration in milliseconds. |
| `call_transferred` | Whether the call was transferred. |
| `call_transferred_to` | Transfer destination number if transferred. |

Use:

```text
GetBigQueryTables
```

before writing final production queries to confirm current schemas.

---

# Useful AI Voice Call Metrics for Ecommerce

AI Voice Calls can be analyzed for many ecommerce metrics.

## Call Volume Metrics

```text
Total AI Voice Calls.
Calls by day/week/month.
Calls by AI Voice Agent.
Calls by inbound vs outbound.
Calls by item type.
Calls by trigger type or account event.
Calls by customer segment.
```

## Call Outcome Metrics

```text
Completed calls.
No-answer calls.
Busy calls.
Voicemail calls.
Cancelled calls.
Error calls.
Robocall-detected calls.
Completion rate.
Error rate.
No-answer rate.
Voicemail rate.
```

## Duration Metrics

```text
Average call duration.
Median call duration.
Total call minutes.
Duration by agent.
Duration by call method.
Duration by status.
Short calls that may indicate hangups.
Long calls that may indicate complex support issues.
```

## Transfer Metrics

```text
Transfer rate.
Transfers by AI Voice Agent.
Transfers by call method.
Transfers by item type.
Transfers by destination number.
Calls that transferred vs completed without transfer.
```

## Customer-Service Metrics

```text
Customers with repeated AI Voice Calls.
Call volume by customer.
Calls tied to support-related item types.
Calls after shipment events.
Calls after subscription renewal failures.
Calls that resulted in notes or metadata.
```

## Revenue Recovery Metrics

```text
Calls tied to declined sales.
Calls tied to salvage transactions.
Calls tied to failed subscription renewals.
Calls tied to trial expiration failures.
Calls followed by successful payment.
Calls followed by completed sale.
Revenue recovered after outbound calls.
Average call duration for recovered vs unrecovered opportunities.
```

## Risk and Chargeback Metrics

```text
Calls tied to chargebacks.
Calls tied to fraud detections.
Calls transferred to support or risk team.
Calls that resulted in notes or metadata.
Calls with repeated customer contact before chargeback.
```

---

# Example BigQuery Metrics

The examples below use the confirmed table:

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

For final production queries, MCP/AI should still use `GetBigQueryTables` to confirm current schemas and should optimize queries to avoid the 30-second limit.

---

## Calls by Day

```sql
SELECT
  DATE(created_at) AS call_date,
  COUNT(*) AS call_count
FROM `revcent.user.ai_voice_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY call_date
ORDER BY call_date DESC
```

---

## Calls by AI Voice Agent

```sql
SELECT
  ai_voice_agent,
  COUNT(*) AS call_count,
  AVG(call_duration) / 1000 AS avg_duration_seconds
FROM `revcent.user.ai_voice_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY ai_voice_agent
ORDER BY call_count DESC
```

---

## Inbound vs Outbound Calls

```sql
SELECT
  call_method,
  COUNT(*) AS call_count,
  AVG(call_duration) / 1000 AS avg_duration_seconds
FROM `revcent.user.ai_voice_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY call_method
ORDER BY call_count DESC
```

---

## Status Distribution

```sql
SELECT
  status,
  COUNT(*) AS call_count,
  ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS percent_of_calls
FROM `revcent.user.ai_voice_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY status
ORDER BY call_count DESC
```

---

## Transfer Rate by Agent

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

---

## Calls by Item Type

```sql
SELECT
  item_type,
  COUNT(*) AS call_count,
  AVG(call_duration) / 1000 AS avg_duration_seconds
FROM `revcent.user.ai_voice_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY item_type
ORDER BY call_count DESC
```

---

## Outbound Declined Sale Call Volume

```sql
SELECT
  DATE(created_at) AS call_date,
  COUNT(*) AS declined_sale_call_count
FROM `revcent.user.ai_voice_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND call_method = 'outbound'
  AND item_type = 'sale'
GROUP BY call_date
ORDER BY call_date DESC
```

If the account needs more exact declined-sale attribution, MCP/AI should join to the `sale`, `transaction`, or related tables after inspecting schemas with `GetBigQueryTables`.

---

# Joining AI Voice Calls to Other Tables

AI Voice Calls become much more valuable when joined to other RevCent tables.

Possible joins:

```text
ai_voice_call.ai_voice_agent → ai_voice_agent.id
ai_voice_call.customer → customer.id
ai_voice_call.sale → sale.id
ai_voice_call.item_id → corresponding item table based on item_type
api_call.ai_voice_call → ai_voice_call.id
```

Examples:

```text
Join calls to AI Voice Agents to show agent names.
Join calls to customers to analyze customer support activity.
Join calls to sales to measure revenue recovery.
Join calls to API calls to audit what system actions the voice agent used.
Join calls to notes/metadata to analyze call outcomes if the agent created notes or inserted metadata.
```

---

# API Call Auditing for Voice Calls

The BigQuery `api_call` table can include:

```text
ai_voice_agent
ai_voice_call
```

This is useful because AI Voice Agents may use system actions during calls, such as:

```text
GetCustomer
GetSale
CreateNote
InsertMetadata
SendSMTPMessage
TriggerFunction
RefundProductSale
RefundShipment
CancelSubscription
```

By analyzing API calls related to an AI Voice Call, a business can answer:

```text
Which system actions did AI Voice Agents use during calls?
How often did calls create notes?
How often did calls insert metadata?
How often did calls send emails?
How often did calls trigger functions?
Which calls involved refunds, subscription changes, or sale creation?
Which calls failed because an API action returned an error?
```

This can help with:

```text
Auditing
Compliance review
Debugging
Operational reporting
AI workflow improvement
Risk management
```

---

---

# AI Voice Calls, API Calls, Payment Attempts, and Revenue Performance

AI Voice Calls can be analyzed together with API Calls to understand what the AI Voice Agent actually did during or around a call.

This is especially useful for ecommerce businesses that want to measure whether AI Voice Agents are producing valuable outcomes, such as:

```text
Creating sales.
Processing pending sales.
Attempting payment recovery.
Adding customer cards.
Refunding transactions.
Refunding product sales.
Refunding shipments.
Refunding subscription renewals.
Sending follow-up emails.
Creating notes.
Inserting metadata.
Triggering Functions.
```

The BigQuery `api_call` table can include these important fields:

| Field | Meaning |
|---|---|
| `type` | API call type. Useful for grouping actions such as sale, transaction, refund, note, metadata, etc. |
| `method` | API call method. Useful for distinguishing create, retrieve, edit, refund, trigger, etc. |
| `code` | API response code. Usually used to determine success/failure. |
| `ai_voice_agent` | AI Voice Agent associated with the API call, if applicable. |
| `ai_voice_call` | AI Voice Call associated with the API call, if applicable. |

The key relationship is:

```text
api_call.ai_voice_call → ai_voice_call.id
```

This allows RevCent users and MCP/AI to report on API actions that happened because of, or during, an AI Voice Call.

---

## Why This Matters

A normal AI Voice Call report can answer:

```text
How many calls happened?
How long were the calls?
How many calls completed?
How many calls transferred?
```

But joining AI Voice Calls with API Calls can answer more valuable business questions:

```text
How many payment attempts happened during AI Voice Calls?
How many sale create attempts succeeded or failed?
How many transaction refunds were performed by voice agents?
How many product sale refunds were performed by voice agents?
How many notes or metadata entries were created after calls?
Which AI Voice Agents are taking the most actions?
Which AI Voice Agents are producing successful payment outcomes?
Which call types create the most revenue-related API activity?
```

This turns AI Voice Call reporting from simple call-center metrics into ecommerce performance reporting.

---

# Payment Attempt Reporting From AI Voice Calls

Payment attempts and payment-related outcomes can be reported by querying `api_call` records where:

```text
api_call.ai_voice_call IS NOT NULL
```

This means the API call is associated with a specific AI Voice Call.

Examples of payment-related API call patterns may include:

```text
sale create
pending sale processing
transaction refund
product sale refund
shipping refund
subscription renewal refund
card add
sale estimate
```

The exact `type` and `method` values should be inspected from the user's BigQuery data because they are stored as API call fields.

MCP/AI should not guess the exact production values. It should first inspect sample values or group by `type` and `method`.

---

## Discover API Action Types Used by AI Voice Calls

Use this query first to discover which API action types and methods are actually present for AI Voice Calls.

```sql
SELECT
  ac.type,
  ac.method,
  COUNT(*) AS api_call_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
WHERE ac.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND ac.ai_voice_call IS NOT NULL
GROUP BY ac.type, ac.method
ORDER BY api_call_count DESC
```

This helps MCP/AI identify the exact values used for operations like sale creation, payment processing, transaction refunding, product sale refunding, and other actions.

---

## API Actions by AI Voice Agent

This query joins AI Voice Calls to AI Voice Agents and API Calls.

It reports what each AI Voice Agent did through system/API actions.

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  avc.call_method,
  ac.type AS api_call_type,
  ac.method AS api_call_method,
  COUNT(*) AS api_call_count,
  SUM(IF(ac.code = 1, 1, 0)) AS success_count,
  SUM(IF(ac.code != 1, 1, 0)) AS failure_count,
  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)
GROUP BY
  ai_voice_agent_id,
  ai_voice_agent_name,
  avc.call_method,
  api_call_type,
  api_call_method
ORDER BY api_call_count DESC
```

This is useful for answering:

```text
Which AI Voice Agent creates the most sales?
Which agent attempts the most refunds?
Which agent has the highest API action success rate?
Which agent has the most failed payment-related actions?
```

---

# Payment Attempt Success/Failure Report

The following query focuses on API actions that look payment-related.

Because exact `type` and `method` values can vary, this query uses keyword matching across `type` and `method`.

MCP/AI should refine this after discovering exact values from the account.

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  avc.call_method,
  ac.type AS api_call_type,
  ac.method AS api_call_method,
  COUNT(*) AS payment_action_count,
  SUM(IF(ac.code = 1, 1, 0)) AS successful_payment_actions,
  SUM(IF(ac.code != 1, 1, 0)) AS failed_payment_actions,
  ROUND(SUM(IF(ac.code = 1, 1, 0)) * 100.0 / COUNT(*), 2) AS payment_action_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,
  avc.call_method,
  api_call_type,
  api_call_method
ORDER BY payment_action_count DESC
```

Use this for:

```text
Payment attempt success/failure.
Refund action success/failure.
Sale creation success/failure.
Card/pending-sale action success/failure.
AI Voice Agent payment-action performance.
```

---

# Revenue Performance Reporting From AI Voice Calls

Revenue performance reporting usually requires joining AI Voice Calls to the related sale or payment tables.

The `ai_voice_call` table includes fields such as:

```text
sale
item_type
item_id
customer
ai_voice_agent
```

The simplest revenue-attribution path is:

```text
ai_voice_call.sale → sale.id
```

or, when the call is associated with a sale item:

```text
ai_voice_call.item_type = 'sale'
ai_voice_call.item_id → sale.id
```

Because RevCent BigQuery schemas should be confirmed before writing final SQL, MCP/AI should always run `GetBigQueryTables` first and verify the `sale` table revenue fields.

---

## Example: AI Voice Agent Call and Related Sale Revenue

The following is a schema-dependent example. MCP/AI must confirm the exact `sale` amount/status fields with `GetBigQueryTables` before running in production.

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  avc.call_method,
  COUNT(DISTINCT avc.id) AS total_calls,
  COUNT(DISTINCT avc.customer) AS unique_customers_called,
  COUNT(DISTINCT avc.sale) AS related_sales,
  SUM(s.amount) AS related_sale_amount,
  AVG(avc.call_duration) / 1000 AS avg_call_duration_seconds,
  SUM(IF(avc.status = 'Completed', 1, 0)) AS completed_calls,
  SUM(IF(avc.call_transferred, 1, 0)) AS transferred_calls
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,
  avc.call_method
ORDER BY related_sale_amount DESC
```

If the `sale` table uses a different field than `amount`, replace `s.amount` with the confirmed revenue field from `GetBigQueryTables`.

This report can answer:

```text
Which AI Voice Agents are associated with the most sale amount?
Which agents have the most calls tied to sales?
What is the average call duration for revenue-generating call contexts?
How do inbound vs outbound voice agents compare?
```

---

## Example: Payment API Actions + Related Sale Context

This query combines:

```text
AI Voice Calls
AI Voice Agents
API Calls
Related Sale
```

It can help connect call activity, payment-related API actions, and related revenue context.

```sql
SELECT
  ava.id AS ai_voice_agent_id,
  ava.name AS ai_voice_agent_name,
  avc.call_method,
  ac.type AS api_call_type,
  ac.method AS api_call_method,
  COUNT(DISTINCT avc.id) AS calls_with_action,
  COUNT(*) AS api_action_count,
  SUM(IF(ac.code = 1, 1, 0)) AS successful_api_actions,
  SUM(IF(ac.code != 1, 1, 0)) AS failed_api_actions,
  SUM(s.amount) AS related_sale_amount
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
LEFT JOIN `revcent.user.sale` s
  ON avc.sale = s.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,
  avc.call_method,
  api_call_type,
  api_call_method
ORDER BY related_sale_amount DESC, api_action_count DESC
```

Important:

```text
This query attributes sale amount based on the sale related to the AI Voice Call.
If the payment action created a new sale that is not the same as avc.sale, the query may need to be adapted using API call metadata, related API output, or other sale linkage available in the account schema.
```

---

# Using API Calls to Audit Voice-Agent Revenue Actions

When an AI Voice Agent is allowed to use payment, sale, card, or refund system actions, the `api_call` table can help audit those actions.

Useful audit questions:

```text
How often did the voice agent attempt to create a sale?
How often did sale creation succeed?
How often did payment actions fail?
How often did the voice agent refund a transaction/product/shipment/subscription renewal?
Which voice agent created the most successful payment-related API actions?
Which calls had payment API failures and may need follow-up?
Did a specific AI Voice Call trigger a refund or sale action?
```

This is especially important when AI Voice Agents are enabled with high-impact system actions such as:

```text
CreateSale
ProcessPendingSale
AddCardToCustomer
RefundTransaction
RefundProductSale
RefundShipment
RefundSubscriptionRenewal
VoidSale
```

MCP/AI should report on these actions using BigQuery rather than paginating through `GetAIVoiceCalls`.

---

# Practical Revenue Performance KPIs

Useful AI Voice Agent revenue-performance KPIs include:

```text
Calls per agent.
Completed calls per agent.
Payment-related API actions per agent.
Payment action success rate.
Payment action failure rate.
Calls with successful sale-related API actions.
Related sale amount by agent.
Average call duration for successful payment outcomes.
Transfer rate for payment-related calls.
Failed payment action follow-up count.
Revenue/action ratio by agent.
```

For a more complete revenue-performance dashboard, combine:

```text
ai_voice_call
ai_voice_agent
api_call
sale
transaction
subscription_renewal
salvage_transaction
metadata
note
```

depending on the account schema and business question.


# Notes, Metadata, and Call Outcomes

AI Voice Calls themselves record call-level details, but durable business outcomes may also be stored as notes or metadata.

Examples:

```text
CreateNote:
"Voice call: customer requested callback tomorrow afternoon."

InsertMetadata:
ai_voice_outcome = callback_requested
```

Recommended pattern:

```text
AI Voice Call = call event and operational details.
Note = concise human-readable call summary.
Metadata = structured outcome for reporting, search, segmentation, and automation.
```

This lets the business answer both:

```text
What happened during this call?
```

and:

```text
How many calls had outcome X?
```

Important:

```text
Do not flood metadata.
Only insert actionable/reportable metadata outcomes.
Do not create play-by-play notes.
Condense each interaction into a single concise note whenever possible.
```

---

# Ecommerce Use Cases

## Declined Sale Recovery

Outbound AI Voice Calls can follow up after failed or declined sales.

Useful metrics:

```text
Calls made after declined sale events.
Completed vs no-answer calls.
Average call duration.
Recovered sales after call.
Call outcomes by metadata.
Transfer rate for complex payment issues.
```

## Subscription Renewal Recovery

Outbound calls can follow up on failed subscription renewals.

Useful metrics:

```text
Calls by failed renewal event.
Completed calls by agent.
Renewal success after call.
Customers requiring multiple contacts.
Call duration for successful vs unsuccessful recoveries.
```

## Trial Expiration Recovery

AI Voice Calls can help customers whose trial expired or failed to convert.

Useful metrics:

```text
Trial expiration call volume.
Call completion rate.
Conversion after call.
No-answer/voicemail rates.
```

## Shipping and Fulfillment Support

Inbound or outbound calls can help with tracking, delivery, and shipment issues.

Useful metrics:

```text
Calls tied to shipping items.
Calls after delivered/shipped events.
Transfer rate to support.
Call topics from notes/metadata.
```

## Chargeback and Risk Workflows

Calls can help detect or respond to dispute risk.

Useful metrics:

```text
Calls tied to chargebacks.
Calls tied to fraud detections.
Calls transferred to risk/support.
Calls followed by notes or AI memos.
```

## Inbound Support

Inbound AI Voice Calls help ecommerce businesses handle support requests at scale.

Useful metrics:

```text
Inbound call volume.
Inbound completion rate.
Average inbound call duration.
Most common related item types.
Transfers to human support.
Repeat callers.
```

## High-Value Customer Outreach

Outbound calls can be triggered for VIPs or high-value customers.

Useful metrics:

```text
Calls to high-LTV customers.
Completion rate by customer segment.
Transfer rate for VIP calls.
Revenue or retention outcomes after calls.
```

---

# Customer Experience Considerations

AI Voice Calls can help recover revenue and support customers, but they must be designed carefully.

Important considerations:

```text
Outbound calls should not interrupt active checkout when a delay would be better.
Filters should still be checked after any delay.
Call limits should prevent repeated or annoying outreach.
Active windows should respect appropriate calling hours.
Instructions should be customer-friendly and specific.
Mutating/payment/refund actions should be enabled only with strict rules.
Transfers should be used when the customer needs a human.
Calls should end politely when the customer does not want help.
```

Good outbound agent behavior:

```text
Helpful
Optional
Respectful
Clear
Non-pressuring
Able to end quickly
Able to transfer when needed
```

Poor outbound behavior:

```text
Calling too soon
Calling repeatedly
Pressuring the customer
Using vague instructions
Overusing system actions
Failing to respect customer preference
```

---

# When to Use GetAIVoiceCall

Use `GetAIVoiceCall` when:

```text
The AI Voice Call ID is known.
The user wants details about one specific call.
The user wants to inspect call status, duration, customer, item, trigger, provider IDs, or integrations.
The MCP needs to debug a specific call.
The MCP needs to determine what item/customer was associated with a call.
```

Example:

```json
{
  "ai_voice_call_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

# When to Use GetAIVoiceCalls

Use `GetAIVoiceCalls` when:

```text
The user wants a small paginated list of calls.
The user wants recent calls in a date range.
The user wants to filter by AI Voice Agent ID.
The user wants to filter by status.
The MCP needs to find an AI Voice Call ID.
```

Required inputs:

```text
date_start
date_end
limit
page
```

Optional filters:

```text
ai_voice_agent_filter
status_filter
```

Do not use `GetAIVoiceCalls` for reporting or metrics.

---

# When to Use BigQueryRunQuery

Use `BigQueryRunQuery` when the user asks for:

```text
How many calls?
Call counts by date.
Call counts by agent.
Average call duration.
Completion rate.
No-answer rate.
Voicemail rate.
Error rate.
Transfer rate.
Calls by item type.
Calls by customer segment.
Calls by related sale/customer.
Revenue recovery reporting.
Payment attempt success/failure by API call type/method.
Revenue performance by joining AI Voice Calls to API Calls, AI Voice Agents, and related sale/payment tables.
Data mining or analytics.
Bulk-style analysis.
```

Recommended workflow:

```text
1. Use GetBigQueryTables to confirm schema.
2. Query `revcent.user.ai_voice_call`.
3. Join other tables when needed.
4. Optimize the query to avoid the 30-second timeout.
5. Use date filters whenever possible.
```

---

# BigQuery Rules

When using `BigQueryRunQuery`:

```text
Use BigQuery Standard SQL.
Use fully qualified table references.
Wrap table names in backticks.
Use `revcent` as project ID.
Use `user` as dataset ID.
Use GetBigQueryTables before writing queries.
Avoid COALESCE.
When using TIMESTAMP_SUB, only use INTERVAL in DAY.
Optimize queries to avoid 30-second timeouts.
```

Correct table reference:

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

---

# MCP/AI Guidance

When helping a user with AI Voice Calls:

1. Determine whether the user wants one call, a small list, or metrics/reporting.
2. Use `GetAIVoiceCall` for one known call ID.
3. Use `GetAIVoiceCalls` only for paginated retrieval.
4. Use `BigQueryRunQuery` for metrics, analytics, and reporting.
5. Use `GetBigQueryTables` before writing BigQuery SQL.
6. Review call method: inbound vs outbound.
7. Review status and duration.
8. Review trigger source: `api`, `account_event`, or `inbound_call`.
9. Review associated customer and item context.
10. Review AI and voice integrations for debugging/provider context.
11. Use related API calls, notes, and metadata to understand what happened during or after the call.
12. For outbound calls, consider customer experience, delay, filters, active windows, and duplicate-call prevention.
13. Do not use paginated call retrieval for counts, aggregations, or data mining.

---

# Summary

AI Voice Calls are the individual call records created when RevCent AI Voice Agents handle inbound calls or initiate outbound calls.

They are created from:

```text
Inbound calls to configured voice agents
Outbound account-event triggers
Outbound on-demand/API triggers using TriggerAIVoiceAgent
```

They are useful because they provide call-level visibility into:

```text
Who was called or who called in
Which AI Voice Agent handled the call
Whether the call was inbound or outbound
Which customer/item was associated
What triggered the call
Which AI and voice integrations were used
Call status
Call duration
Transfer behavior
Provider call/session IDs
```

AI Voice Calls can also be joined with API Calls to report on payment attempts, sale creation, refunds, and other voice-agent system actions.

For ecommerce businesses, AI Voice Calls support:

```text
Revenue recovery
Customer support
Subscription renewal follow-up
Trial expiration recovery
Shipment support
Chargeback/risk workflows
High-value customer outreach
Inbound support scaling
Call quality monitoring
Operational reporting
AI workflow auditing
```

Use:

```text
GetAIVoiceCall for one call.
GetAIVoiceCalls for small paginated retrieval.
BigQueryRunQuery for metrics, reporting, and analytics.
```

The most important reporting table is:

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

Used well, AI Voice Calls turn live AI phone conversations into measurable ecommerce support, recovery, and operations data.


---
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.