# RevCent MCP Operation: `TriggerAIVoiceAgent`

This document explains the `TriggerAIVoiceAgent` MCP operation, which immediately starts an outbound AI Voice Call for an on-demand outbound AI Voice Agent.

Sources:
- RevCent MCP schema for `TriggerAIVoiceAgent`
- RevCent KB: `https://kb.revcent.com/tools/ai/voice-agents`
- RevCent AI Voice Agent Overview — `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md`

---

---

# Read the AI Voice Agent Overview First

Before creating, editing, triggering, or deeply configuring AI Voice Agents, MCP/AI should read the AI Voice Agent overview:

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

The overview explains AI Voice Agents as a whole, including:

```text
What AI Voice Agents are.
How inbound and outbound AI Voice Agents work.
Required AI and voice third-party integrations.
Realtime AI model and phone integration requirements.
Instruction design.
System actions.
Inbound caller matching.
Outbound triggers.
On-demand triggering.
Account-event triggering.
Filter Functions.
Pre-agent Functions.
Compiled call input data.
Handlebars usage.
AI Voice Snippets.
Call limits.
Active windows.
Customer-experience considerations.
Delay strategy.
Safety, compliance, and best practices.
```

This operation file is focused on the specific API/MCP operation. The overview provides the broader conceptual context MCP/AI should understand before making design decisions about an AI Voice Agent.

## Operation Summary

`TriggerAIVoiceAgent` triggers a specific AI Voice Agent and immediately creates an outbound AI Voice Call.

Important requirements:

- The AI Voice Agent must have `call_method = "outbound"`.
- The AI Voice Agent must have trigger setting `on_demand`.
- Event-triggered agents cannot be triggered via this operation.
- Inbound agents cannot be triggered via this operation.
- The request must provide an item type and item ID.
- RevCent uses the item to populate item details and determine the customer phone number associated with the call.

If the AI Voice Agent ID is unknown, use `GetAIVoiceAgents` first to find it by name or description.

---

## Required Input

| Field | Type | Required | Description |
|---|---:|---:|---|
| `source_type` | enum | Yes | Must equal `item`. |
| `item_type` | enum | Yes | Item type to use as the call context. |
| `item_id` | string | Yes | 20-character ID of the item. |
| `ai_voice_agent_id` | string | Yes | 20-character AI Voice Agent ID. |

---

## `item_type`

Allowed values:

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

Use the item type most relevant to why the call is being made.

---

# Request Example

```json
{
  "source_type": "item",
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "ai_voice_agent_id": "YYYYYYYYYYYYYYYYYYYY"
}
```

---

# Output Schema

A successful response returns:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "ai_voice_call_id": "ZZZZZZZZZZZZZZZZZZZZ",
  "ai_voice_agent_id": "YYYYYYYYYYYYYYYYYYYY",
  "customer_id": "CCCCCCCCCCCCCCCCCCCC",
  "result": "..."
}
```

---

# What Happens When Triggered

1. RevCent validates the AI Voice Agent.
2. RevCent verifies the agent is outbound and on-demand.
3. RevCent retrieves the provided item details.
4. RevCent identifies the customer associated with the item.
5. RevCent creates an AI Voice Call.
6. RevCent initiates an outbound phone call to the customer's phone number.
7. If configured, the pre-agent Function runs before the call starts.
8. RevCent compiles the agent instructions using Handlebars.
9. The AI begins the live voice conversation.

---

# Relationship to Functions

## Pre-Agent Function

If configured, it runs immediately before the call begins and returns JSON for instruction Handlebars.

## Filter Function

A filter Function is normally used with outbound `account_event` triggers. `TriggerAIVoiceAgent` is explicit on-demand triggering, so filter eligibility should be handled before calling this operation if needed.

## Function Triggered During Instructions

If `TriggerFunction` is enabled in `settings.system_actions`, the AI may trigger Functions during the live conversation when instructions tell it to do so.

---

# Safety and Consent Guidance

Because this operation immediately initiates an outbound phone call:

- Do not call it unless the user explicitly wants to trigger a call.
- Confirm the agent is intended for on-demand outbound calls.
- Confirm the item and customer are correct.
- Confirm phone outreach is appropriate.
- Respect call windows and customer preferences.
- Avoid duplicate calls.
- Review `max_outbound_calls_per_customer` and other limits.
- Do not trigger test calls to real customers unintentionally.

---

# Pre-Trigger Checklist

0. Confirm the AI Voice Agent overview has been reviewed when deciding whether this on-demand call is appropriate.

1. Confirm the AI Voice Agent ID.
2. Use `GetAIVoiceAgent` if needed to confirm configuration.
3. Confirm `call_method = outbound`.
4. Confirm trigger setting is `on_demand`.
5. Confirm the agent is enabled.
6. Confirm the relevant `item_type`.
7. Retrieve the item if needed.
8. Confirm the item has an associated customer.
9. Confirm the customer has a phone number.
10. Confirm the call should happen now.
11. Confirm active window and call limits are acceptable.
12. Trigger the agent.
13. Save the returned `ai_voice_call_id`.

---

# Quick Reference

Valid request:

```json
{
  "source_type": "item",
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "ai_voice_agent_id": "YYYYYYYYYYYYYYYYYYYY"
}
```

Only valid for:

```text
call_method = outbound
trigger = on_demand
```


---

# Overview Reference

MCP/AI should read the AI Voice Agent overview for broad conceptual understanding:

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