# RevCent MCP Operation: `GetAIVoiceCall` This document explains how MCP/AI clients should use the `GetAIVoiceCall` operation in RevCent. `GetAIVoiceCall` retrieves the details of one specific AI Voice Call using a 20-character AI Voice Call ID. 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 `GetAIVoiceCall` - RevCent operation schema for `GetAIVoiceCalls` - 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 `GetAIVoiceCall` retrieves a single AI Voice Call. Use this operation when: ```text The ai_voice_call_id is known. The user wants details for one specific AI Voice Call. MCP/AI needs to debug or inspect one call. MCP/AI needs the associated customer, item, status, trigger, duration, provider IDs, or integrations for one call. ``` Do not use this operation for: ```text Counts. Metrics. Aggregations. Reports. Data mining. Call performance dashboards. Revenue reporting. Payment action reporting. Bulk analysis. ``` For those use cases, use: ```text BigQueryRunQuery ``` --- # Required Input | Field | Type | Required | Description | |---|---:|---:|---| | `ai_voice_call_id` | string | Yes | 20-character AI Voice Call ID. | Example request: ```json { "ai_voice_call_id": "XXXXXXXXXXXXXXXXXXXX" } ``` --- # What an AI Voice Call Represents An AI Voice Call is the individual call record created when an AI Voice Agent handles an inbound call or initiates an outbound call. AI Voice Calls may be created from: ```text Inbound customer calls. Outbound account-event triggers. Outbound on-demand/API triggers using TriggerAIVoiceAgent. ``` An AI Voice Call is not the same thing as an AI Voice Agent. ```text AI Voice Agent = configured agent/instructions/tools/triggers. AI Voice Call = one specific call handled by that agent. ``` --- # Important Response Fields `GetAIVoiceCall` can return 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 provider/source 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 a customer is associated. | | `source_type` | Usually `item` if the call is tied to an item. | | `item_type` | Type of item associated with the call. | | `item_id` | ID of the associated item. | | `status` | Current AI Voice Call status. | | `trigger` | Information about what created the call. | | `third_party_integration_ai` | AI provider integration used for the call. | | `third_party_integration_voice` | Voice provider integration used for the call. | --- # Associated Customer If a customer is associated with the AI Voice Call, the response can include customer information such as: ```text id email first_name last_name phone address enabled blocked metadata created_date_unix updated_date_unix ``` This helps MCP/AI understand who participated in the call and connect the call to customer history. Use the customer object to answer questions like: ```text Who was this call with? Was this call associated with an existing customer? What customer metadata existed at the time of retrieval? Is the customer enabled or blocked? ``` --- # Associated Item Context AI Voice Calls may be associated with a specific item. Supported `item_type` values include: ```text sale customer product_sale shipping subscription subscription_renewal salvage_transaction transaction chargeback fraud_detection ``` Examples: ```text Declined sale recovery call → item_type = sale Customer support call → item_type = customer Shipment support call → item_type = shipping Renewal recovery call → item_type = subscription_renewal Fraud verification call → item_type = fraud_detection Chargeback prevention call → item_type = chargeback ``` If deeper context is needed, MCP/AI should retrieve the associated item using the appropriate `Get...` operation. --- # Call Status `GetAIVoiceCall` can return a status such as: ```text Active Complete Timer Cancelled Error ``` Status is useful for understanding one call, but do not use this operation repeatedly to produce status counts. For status counts, completion rates, error rates, no-answer/voicemail reporting, or call dashboards, use: ```text BigQueryRunQuery ``` --- # Trigger Information The `trigger` object explains what created the AI Voice Call. Trigger source values include: ```text api account_event inbound_call ``` Examples: | Trigger source | Meaning | |---|---| | `api` | The call was created by API/MCP/on-demand triggering. | | `account_event` | The call was created by an outbound account-event AI Voice Agent. | | `inbound_call` | The call was created because someone called an inbound AI Voice Agent number. | If `trigger.source = account_event`, the response may include: ```text trigger.notation ``` Example: ```text sale.created.failed.declined subscription_renewal.updated.failed ``` If `trigger.source = api`, the response may include API call details. --- # AI and Voice Integrations The response can include: ```text third_party_integration_ai third_party_integration_voice ``` These identify the configured third-party integrations used by the call. Conceptually: ```text third_party_integration_ai = realtime AI/model integration. third_party_integration_voice = phone/voice provider integration. ``` This helps with: ```text Provider debugging. Model/source auditing. Voice provider tracing. Integration troubleshooting. Call quality investigation. Cost/performance analysis. ``` --- # Debugging One AI Voice Call Use `GetAIVoiceCall` to debug a single call. Useful questions: ```text Was the call inbound or outbound? Which customer was associated? Which item was associated? What triggered the call? What was the call status? How long did it last? Which voice provider IDs were involved? Which AI provider/model/session was involved? Which AI and voice integrations were used? ``` For deeper debugging, also consider: ```text GetAIVoiceAgent GetCustomer GetSale / GetShipment / GetSubscription / other associated item operations BigQueryRunQuery against api_call where ai_voice_call = this call ID ``` --- # API Calls Associated With One AI Voice Call AI Voice Agents may use system actions during a call. Examples: ```text GetCustomer GetSale CreateNote InsertMetadata SendSMTPMessage TriggerFunction AddCardToCustomer ProcessPendingSale CreateSale RefundTransaction RefundProductSale RefundShipment RefundSubscriptionRenewal ``` To inspect API/system actions associated with one specific call, use BigQuery: ```sql SELECT created_at, id, type, method, code FROM `revcent.user.api_call` WHERE ai_voice_call = 'XXXXXXXXXXXXXXXXXXXX' ORDER BY created_at ASC ``` This is useful when the user asks: ```text What did the AI Voice Agent do during this call? Did it create a note? Did it insert metadata? Did it attempt a payment action? Did a refund action succeed or fail? Did a function run? ``` --- # GetAIVoiceCall vs GetAIVoiceCalls vs BigQueryRunQuery | Goal | Use | |---|---| | Retrieve one AI Voice Call by ID | `GetAIVoiceCall` | | Retrieve a small filtered page of calls | `GetAIVoiceCalls` | | Count calls | `BigQueryRunQuery` | | Report calls by day/agent/status | `BigQueryRunQuery` | | Analyze average duration | `BigQueryRunQuery` | | Report transfer rate | `BigQueryRunQuery` | | Analyze API/system actions during calls | `BigQueryRunQuery` | | Analyze payment attempts or revenue performance | `BigQueryRunQuery` | | Data mining or bulk analysis | `BigQueryRunQuery` | --- # BigQuery Reporting Reminder For reporting and metrics, use: ```text BigQueryRunQuery ``` Relevant BigQuery tables include: ```text revcent.user.ai_voice_call revcent.user.ai_voice_agent revcent.user.api_call sale / transaction / salvage_transaction / subscription_renewal when revenue attribution is needed ``` Useful relationships: ```text api_call.ai_voice_call → ai_voice_call.id api_call.ai_voice_agent → ai_voice_agent.id ai_voice_call.ai_voice_agent → ai_voice_agent.id ai_voice_call.sale → sale.id ``` MCP/AI should call `GetBigQueryTables` before writing final SQL. --- # Example: Retrieve API Actions for This Call ```sql SELECT ac.created_at, ac.type, ac.method, ac.code FROM `revcent.user.api_call` ac WHERE ac.ai_voice_call = 'XXXXXXXXXXXXXXXXXXXX' ORDER BY ac.created_at ASC ``` --- # Example: Payment/Refund Actions for This Call ```sql SELECT ac.created_at, ac.type, ac.method, ac.code FROM `revcent.user.api_call` ac WHERE ac.ai_voice_call = 'XXXXXXXXXXXXXXXXXXXX' AND REGEXP_CONTAINS( LOWER(CONCAT(ac.type, ' ', ac.method)), r'sale|payment|transaction|refund|card|pending' ) ORDER BY ac.created_at ASC ``` MCP/AI should refine this query after inspecting actual `api_call.type` and `api_call.method` values. --- # Validation Checklist Before calling `GetAIVoiceCall`: 1. The user wants one specific AI Voice Call. 2. `ai_voice_call_id` is known. 3. `ai_voice_call_id` is 20 characters. 4. The user is not asking for a report, metric, count, aggregation, or data mining task. 5. If deeper context is needed, prepare to retrieve the related customer/item. 6. If system-action history is needed, use BigQuery against `api_call.ai_voice_call`. 7. If broad metrics are requested, use `BigQueryRunQuery`, not `GetAIVoiceCall`. --- # Common Mistakes ## Mistake: Using GetAIVoiceCall for Metrics Wrong: ```text Call GetAIVoiceCall repeatedly to count completed calls. ``` Correct: ```text Use BigQueryRunQuery against revcent.user.ai_voice_call. ``` ## Mistake: Confusing Agent and Call Wrong: ```text Treat AI Voice Agent ID as the AI Voice Call ID. ``` Correct: ```text Use ai_voice_agent_id for agent configuration. Use ai_voice_call_id for one call record. ``` ## Mistake: Ignoring API Calls Wrong: ```text Only inspect the call record to decide whether the agent attempted payment or refund actions. ``` Correct: ```text Use BigQueryRunQuery on api_call where ai_voice_call = the call ID. ``` --- # Key Takeaways ```text GetAIVoiceCall retrieves one specific AI Voice Call by ID. ``` ```text AI Voice Calls are created by inbound calls, outbound account-event triggers, or outbound on-demand/API triggers. ``` ```text The call record can include status, duration, trigger source, customer, item context, provider IDs, AI integration, and voice integration. ``` ```text Use BigQueryRunQuery for reporting, metrics, API action auditing, 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.