# RevCent MCP Operation: `EditAIVoiceAgent`

This document explains the `EditAIVoiceAgent` MCP operation and how to safely update an existing AI Voice Agent.

Sources:
- RevCent MCP schema for `EditAIVoiceAgent`
- 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

`EditAIVoiceAgent` edits a previously created AI Voice Agent using its 20-character `ai_voice_agent_id`.

Use it to update name, description, enabled status, call method, pre-agent Function, voice, instructions, limits, system actions, active window, outbound trigger settings, AI integration, and voice/Twilio integration.

Important:

- `ai_voice_agent_id` is required.
- Only include fields you want to modify.
- Omitted fields remain unchanged.
- For nested objects like `settings`, be careful to preserve fields you do not intend to change.
- Disable the agent before major edits, especially instructions, system actions, call method, or trigger settings.

---

# Critical Requirement: Do Not Edit to Minimal Agent Instructions

AI Voice Agent instructions are the most important and critical part of an AI Voice Agent.

The MCP should **never** edit an AI Voice Agent to use minimal, generic, placeholder, or example-only instructions such as:

```markdown
# Role & Objective
- You are a customer service agent.

# Conversation Flow
- Greet the caller.
- Help the caller.
- End the call.
```

That kind of minimal instruction is not sufficient for a production or test AI Voice Agent because the AI Voice Agent speaks directly with customers or prospects. Poorly specified edits can cause the agent to:

- Say the wrong thing.
- Use the wrong tone.
- Ask for unnecessary information.
- Fail to verify the caller.
- Misuse system actions.
- Process payments, refunds, cards, subscriptions, or sales incorrectly.
- Miss required compliance language.
- Call customers at the wrong time.
- Fail to transfer or end calls correctly.
- Create a bad customer experience.

When editing an AI Voice Agent, the MCP should treat the revised instructions as the core change being designed and reviewed, not as a simple text field.

---

## Required MCP Behavior Before Editing Instructions

Before submitting an `EditAIVoiceAgent` request, confirm the AI Voice Agent overview has been reviewed when making broader design decisions.

Before submitting an `EditAIVoiceAgent` request that changes `settings.instructions.markdown`, the MCP should gather enough information to write detailed, specific, accurate revised instructions.

If the user has not provided enough detail, the MCP should ask targeted questions before generating the final edit request.

The MCP should ask about:

| Area | What to Clarify |
|---|---|
| Reason for edit | What exactly needs to change in the current agent behavior? |
| Current issue | What is the agent doing wrong, missing, or needing to improve? |
| Desired outcome | What should the edited agent do after the change? |
| Call method | Is the agent inbound or outbound? Is that changing? |
| Audience | Who will the agent speak to: customers, prospects, declined-sale customers, subscribers, refund requesters, etc.? |
| Trigger | For outbound agents, is the trigger on-demand or account-event based? |
| Trigger item | What item type drives the call: customer, sale, shipping, subscription, renewal, trial, transaction, chargeback, fraud detection, etc.? |
| Business context | What product, campaign, brand, store, or offer is involved? |
| Conversation flow | What should the agent do first, second, third, and last? |
| Verification | What must the agent verify before discussing account details or taking action? |
| System actions | Which system actions should be added, removed, or kept? |
| Prohibited actions | What should the AI never do? |
| Payment behavior | Can the agent collect a card, add a card, process a pending sale, estimate a sale, or create a sale? |
| Refund behavior | Can the agent issue refunds? If yes, under what rules? |
| Subscription behavior | Can the agent activate, suspend, cancel, edit, or renew subscriptions? |
| Transfer behavior | When should the agent transfer, and to what phone number? |
| End-call behavior | When should the agent end the call? |
| Tone | Friendly, professional, sales-focused, support-focused, empathetic, concise, etc. |
| Language | English only or other language rules. |
| Escalation | What should happen if the caller is angry, confused, asks for a human, or threatens a chargeback? |
| Compliance | Required legal, consent, recording, payment, refund, or subscription language. |
| Metadata | Should the agent insert call outcome metadata? If yes, what names and values? |
| Email follow-up | Should the agent send an Email Template after or during the call? |
| Function usage | Does the agent need filter Functions, pre-agent Functions, or live-call `TriggerFunction` behavior? |
| Testing limits | Should the agent remain disabled, be limited by campaign, or use stricter call limits after the edit? |

---

## Required MCP Review Step Before Submitting Instruction Edits

Before editing the AI Voice Agent, the MCP should display the proposed revised `settings.instructions.markdown` to the user for review.

The MCP should explicitly ask the user to review and approve or revise the instructions before calling `EditAIVoiceAgent`.

Recommended review message:

```text
Below are the proposed revised AI Voice Agent instructions. Please review them carefully. These instructions control what the AI says, when it uses system actions, when it transfers, when it ends the call, and what it is not allowed to do. Tell me any changes before I edit the AI Voice Agent.
```

The MCP should not submit an `EditAIVoiceAgent` request that changes instructions until the user has had a chance to review the drafted instructions, unless the user explicitly instructs the MCP to proceed without review.

---

## Instruction Edit Standard

Revised instructions should be:

- Specific to the user’s stated use case and edit goal.
- Written in structured Markdown.
- Detailed enough for a live customer-facing call.
- Explicit about when the AI should and should not use system actions.
- Explicit about when the AI should verify the caller.
- Explicit about what the AI should not say or do.
- Explicit about transfer and end-call behavior.
- Explicit about payment, refund, subscription, shipment, or sale behavior when relevant.
- Personalized with Handlebars only when the relevant input data is available.
- Consistent with the selected `call_method`, outbound trigger, enabled system actions, pre-agent Function, and filter Function.

The MCP should avoid generic instruction edits and instead revise the instructions around the user’s actual intended workflow.

---

## Recommended Instruction Structure for Edits

When replacing or substantially editing instructions, use a structure like this as the starting point, then customize every section to the user’s specific use case:

```markdown
# Role & Objective
- Define exactly who the agent is and what outcome it is trying to achieve.

# Call Context
- Explain why this call is happening.
- Use Handlebars data when available.

# Personality & Tone
- Define tone, pacing, and language rules.

# Safety & Boundaries
- Define what the agent must never do.

# Verification Rules
- Define what must be verified before discussing private account information or taking actions.

# Conversation Flow
## 1) Opening
- Explain exactly how to start the call.

## 2) Identify Need / Confirm Context
- Explain what the agent should ask or confirm.

## 3) Resolve / Offer / Action
- Explain what the agent should do based on the caller’s response.

## 4) Use System Actions
- Explain exactly which actions are allowed and when.

## 5) Escalation / Transfer
- Explain when to transfer or escalate.

## 6) Close
- Explain how to summarize, say goodbye, and end the call.

# System Action Rules
- List each enabled system action and the exact situations where it may be used.

# Data Handling Rules
- Explain how to use available customer/item/pre-agent data.

# Failure Handling
- Explain what to do when lookup, payment, refund, or Function actions fail.

# End Call Rules
- Explain when and how to end the call.
```

Do not use this structure as a generic final edit. Fill it in with the user’s actual business details.


---

## Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `ai_voice_agent_id` | string | Yes | 20-character AI Voice Agent ID. |

Minimal request:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

# Simple Edits

Rename:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Outbound - Declined Sale Recovery v2"
}
```

Disable:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

Enable:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": true
}
```

---

# Safe Editing Workflow

1. Retrieve the current agent with `GetAIVoiceAgent`.
2. Disable the agent before major changes.
3. Identify exactly what behavior should change and what should remain unchanged.
4. If editing instructions, ask the user for the specific purpose, nuance, call flow, allowed actions, prohibited actions, verification rules, and escalation behavior.
5. Draft detailed revised instructions specific to the user’s use case.
6. Display the revised instructions to the user for review and edits before submitting `EditAIVoiceAgent`.
7. Edit only intended fields.
8. If editing `settings`, preserve nested settings that should remain unchanged.
9. Confirm system actions and instructions match.
10. Test with a controlled call or event.
11. Review call outcomes and costs.
12. Re-enable after validation.

---

# Editing Instructions

Instructions are in:

```json
settings.instructions.markdown
```

This is the most important editable field on an AI Voice Agent.

The MCP should not replace existing instructions with minimal, generic, or placeholder instructions. If instructions are being edited, the MCP should either:

1. Make a precise targeted edit while preserving the rest of the existing instruction document, or
2. Draft a complete, detailed replacement instruction document specific to the user’s workflow.

In both cases, the MCP should display the revised instructions to the user for review before submitting `EditAIVoiceAgent`.

---

## Minimal Instruction Edits Are Not Acceptable

Do not submit instruction edits like this:

```json
{
  "settings": {
    "instructions": {
      "markdown": "# Role & Objective\n- You are an inbound customer service agent.\n\n# Conversation Flow\n- Greet the caller.\n- Help the caller.\n- End the call."
    }
  }
}
```

That is only a sketch, not a safe live-call instruction set.

A real instruction edit should define:

- Agent role and objective.
- Call context.
- Tone and pacing.
- Verification rules.
- Conversation flow.
- System action rules.
- What the agent may do.
- What the agent must never do.
- Payment/refund/subscription/shipping/sale rules, if relevant.
- Data lookup rules.
- Function usage rules.
- Transfer/escalation behavior.
- Failure handling.
- End-call rules.

---

## Targeted Instruction Edit Example

If the user asks for a small change, preserve the existing instructions and only update the necessary section.

Example user request:

```text
Make the agent transfer to support if the customer asks for a human.
```

Appropriate instruction section to add or update:

```markdown
# Escalation / Transfer Rules
- If the caller asks to speak with a human, representative, supervisor, manager, or support agent, politely acknowledge the request.
- Do not try to persuade the caller to continue with the AI.
- Say: "I can connect you with someone who can help."
- Transfer the call to +12345678900.
- If transfer fails, apologize and create a note with the caller's request if `CreateNote` is enabled.
```

---

## Full Instruction Replacement Example Shape

A full replacement should be detailed and use structured Markdown:

```markdown
# Role & Objective
- You are an outbound payment recovery agent for {{agent.name}}.
- Your goal is to help the customer complete a pending sale after a declined payment.

# Call Context
{{#if item.has_item_details}}
- This call is about the item: {{item.item_type}} {{item.item_id}}.
{{/if}}
{{#if customer.verified}}
- The customer is {{customer.first_name}} {{customer.last_name}}.
{{/if}}

# Safety & Boundaries
- Do not promise refunds, discounts, or delivery dates unless verified by an allowed system action or explicitly provided in the instructions.
- Do not process a payment unless the customer clearly agrees.

# Verification Rules
- Before discussing private account details, verify the caller using at least one identifying detail.

# Conversation Flow
## 1) Opening
- Politely introduce yourself and state the reason for the call.

## 2) Confirm Intent
- Ask whether the customer would like help completing the order.

## 3) Payment Help
- If the customer wants to proceed and `AddCardToCustomer` is enabled, collect card information carefully.
- Do not interrupt while the customer provides card details.
- If `ProcessPendingSale` is enabled, process the pending sale only after the customer clearly authorizes it.

## 4) Close
- Summarize the outcome.
- If no further help is needed, say goodbye and end the call.

# System Action Rules
- Use `GetSale` if sale details are not already available.
- Use `GetCustomer` if customer details need to be refreshed.
- Use `CreateNote` at the end of the call to summarize the outcome.
```

The exact instructions must be tailored to the user’s agent, enabled system actions, call method, and trigger.

---

## Best Practices for Editing Instructions

- Keep instructions structured with Markdown headings.
- Preserve existing useful instructions unless the user asks to replace them.
- Use clear conversation flow steps.
- Be explicit about when to use each enabled system action.
- Remove or revise instruction references to system actions that are not enabled.
- Include transfer and end-call rules.
- Include refund/payment/card/subscription limits when those actions are enabled.
- Use Handlebars for personalization only when the relevant data exists.
- Use `{{#if ...}}` guards around optional data.
- Test after every significant instruction change.
- Keep the agent disabled while testing major instruction edits.


---

# Editing System Actions

System actions are API operations the AI may call during the live conversation.

They are permissions, not suggestions. If an action is enabled, the AI may attempt to use it when the instructions tell it to do so. If an action is not enabled, the AI cannot use it.

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "system_actions": [
      "SearchCustomers",
      "GetCustomer",
      "GetSale",
      "CreateNote"
    ]
  }
}
```

When editing `settings.system_actions`, the MCP should review the agent instructions at the same time. The enabled actions and instruction rules must match.

---

## System Action Editing Rules

Before adding a system action, confirm:

1. The user actually wants the AI to perform that capability.
2. The instructions explain exactly when to use it.
3. The instructions explain what to do if the action fails.
4. The action is safe for the agent’s call type and audience.
5. The action is necessary; do not add actions “just in case.”

Before removing a system action, check whether the instructions reference it. If the instructions still tell the AI to use a removed action, edit the instructions too.

Recommended principle:

```text
If the instructions do not explicitly explain when the AI should use a system action, do not include that system action.
```

---

## Data Retrieval Actions

Data retrieval actions are usually safer than write/payment/refund actions, but they should still be intentional.

| Action | Include When | Remove / Do Not Include When |
|---|---|---|
| `SearchCustomers` | Inbound callers may not match by phone, and the agent should search by email, phone, or name. | The agent should only help automatically matched callers or supplied outbound item context. |
| `GetCustomer` | The agent needs current customer details, customer status, metadata, or customer context. | The call does not require customer-specific account information. |
| `GetSale` | The agent needs sale, order, pending payment, or checkout details. | The call is not about a sale/order. |
| `GetShipment` | The agent needs tracking, shipment status, or fulfillment details. | Shipping is not part of the workflow. |
| `GetSubscription` | The agent handles subscription status, cancellation, suspension, activation, or renewal questions. | Subscriptions are irrelevant. |
| `GetSubscriptionRenewal` | The call is about a failed, successful, or upcoming renewal. | Renewals are irrelevant. |
| `GetTransaction` | The agent needs credit card transaction or refund context. | The call does not involve transaction/payment history. |
| `GetPendingRefund` | The agent needs pending refund details. | Refund status is not part of the workflow. |
| `GetTrial` | The call is about trial expiration or cancellation. | Trials are irrelevant. |

Important: An AI Voice Agent can always pull customer, sale, shipment, subscription, renewal, transaction, trial, and other data during the call **only if** the relevant system action is enabled and the instructions tell it when to use that action.

For example:

- Add `GetCustomer` if the agent should retrieve customer details during the call.
- Add `GetSale` if the agent should retrieve sale/order details during the call.
- Add `GetShipment` if the agent should retrieve shipment details during the call.

---

## Write / Mutating Actions

Mutating actions change account data or create side effects. Include them only when the workflow requires them and the instructions define strict rules.

| Action | Include When | Required Instruction Detail |
|---|---|---|
| `CreateNote` | The agent should log call outcomes or customer requests. | When to create the note and what it should contain. |
| `InsertMetadata` | The agent should tag an item/customer with call outcome metadata. | Exact metadata names and allowed values. |
| `SendSMTPMessage` | The agent should send an Email Template during or after the call. | Which template to use, when to send it, and custom arguments. |
| `EditShipment` | The agent may update shipment data. | Exactly which fields may be edited and under what conditions. |
| `EditSubscription` | The agent may edit subscription details. | Exactly what changes are allowed. |
| `ActivateSubscription` / `SuspendSubscription` / `CancelSubscription` / `RenewSubscription` | Subscription support workflows require these actions. | Verification, eligibility, customer consent, and confirmation language. |
| `AddFraudAlert` | The agent should flag suspicious activity. | What behavior qualifies as suspicious. |

Do not include mutating actions just in case.

---

## Payment, Card, Sale, and Refund Actions

These actions are high-impact and should be enabled only with detailed, restrictive instructions.

| Action | Include When | Remove / Do Not Include When |
|---|---|---|
| `AddCardToCustomer` | The agent is explicitly allowed to collect and add a customer card. | The agent should not handle payment information. |
| `ProcessPendingSale` | The agent is helping complete an existing pending sale. | The agent should not attempt payment processing. |
| `CreateSale` | The agent is allowed to create a new sale during the call. | The agent is support-only or should not sell/process orders. |
| `EstimateSale` | The agent needs to quote totals before creating or processing a sale. | Pricing or checkout is not part of the call. |
| `VoidSale` | The agent may void a sale under strict conditions. | Voiding should be handled by humans. |
| `RefundTransaction` | The agent may refund credit card transactions. | Refunds require human approval. |
| `RefundProductSale` | The agent may refund product-level sale items. | Product refunds require human review. |
| `RefundShipment` | The agent may refund shipping. | Shipping refunds require human review. |
| `RefundSubscriptionRenewal` | The agent may refund subscription renewals. | Subscription refunds require human review. |
| `CancelTrial` | The agent may cancel trials. | Trial cancellations require human review. |

If any payment, card, sale, or refund action is enabled, instructions must specify:

- What the agent must verify first.
- Whether customer consent is required.
- Maximum number of attempts.
- Maximum refund amount or exact refund rules.
- When to refuse.
- When to transfer to a human.
- What note/metadata to create after the action.
- What to say if the action fails.
- Whether the agent may retry.

---

## `TriggerFunction`

Enable `TriggerFunction` only when the AI needs to run custom logic during the live call.

Use cases:

- Look up external CRM data.
- Generate a customer-specific offer.
- Validate an external account number.
- Call an external eligibility API.
- Calculate a custom discount.
- Log a custom event in a third-party system.
- Retrieve business-specific data not available from standard RevCent actions.

Do not include `TriggerFunction` when:

- The data can be generated before the call with a pre-agent Function.
- The Function is only needed to decide whether the call should happen; use a filter Function instead.
- The AI does not need custom logic during the live conversation.
- The Function’s behavior is not clearly explained in instructions.

If `TriggerFunction` is enabled, the instructions should identify:

- Which Function or type of Function the AI should look for.
- When the AI should trigger it.
- What arguments it should provide.
- What to do with the Function response.
- What to say if the Function fails.


---

# Editing Limits and Active Window

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "limits": {
      "max_outbound_calls_per_customer": 1,
      "max_calls_per_day": 50,
      "max_duration": 15
    },
    "active_window": {
      "enabled": true,
      "start_hour": 9,
      "end_hour": 17,
      "timezone": "America/New_York",
      "inactive_forward_number": "+12345678900"
    }
  }
}
```

---

# Editing Outbound Trigger Settings

Change to on demand:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "on_demand"
    }
  }
}
```

Change to account event:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "account_event",
      "account_event": {
        "notation": "sale.created.failed.declined",
        "delay_enabled": true,
        "time_value": 2,
        "time_unit": "minutes"
      },
      "limits": {
        "max_calls_per_item": 1
      }
    }
  }
}
```

---

# Removing Functions

Remove pre-agent Function:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "pre_agent_function": ""
}
```

Remove filter Function:

```json
{
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "account_event",
      "account_event": {
        "filter_function": ""
      }
    }
  }
}
```

---



---
---

# Outbound Delay Strategy for Checkout and Customer Experience

For outbound AI Voice Agents, the delay setting is an important customer-experience and conversion setting.

A delay controls how long RevCent waits after the triggering account event before attempting the outbound call.

This is especially important for checkout-related events, such as:

```text
sale.created.success.pending
sale.created.failed
sale.created.failed.declined
trial.updated.expired.failed
subscription_renewal.updated.failed
```

In these scenarios, the customer may still be actively attempting checkout, correcting payment information, reviewing the order, checking their bank app, trying a different card, or deciding whether to complete the purchase.

Calling too quickly can interrupt that process.

---

## Why Delay Matters

An outbound AI Voice Agent call can help recover revenue, but it can also disrupt the customer if it happens at the wrong time.

If the customer is still in the checkout flow, an immediate phone call may:

- Distract the customer from completing checkout.
- Make the customer feel monitored or pressured.
- Cause the customer to abandon the purchase.
- Create confusion if they are still actively fixing the issue.
- Feel intrusive if the event only happened seconds ago.
- Reduce trust if the customer thinks the business is reacting too aggressively.

For checkout-related workflows, the MCP should not treat “call as soon as possible” as the default best behavior.

The delay period should be chosen intentionally.

---

## When a Delay Is Usually Appropriate

A delay is usually appropriate when the customer may still resolve the issue without a call.

Examples:

```text
Customer has a pending sale and may still be checking out.
Customer had a soft payment decline and may try another card.
Customer may be correcting billing details.
Customer may be going through 3DS/bank verification.
Customer may be deciding whether to complete an upsell.
Customer may still be browsing or interacting with checkout.
```

In these cases, a short delay can give the customer time to complete the purchase naturally before the AI Voice Agent intervenes.

Example strategy:

```text
Pending checkout follow-up:
delay_enabled = true
time_value = 5
time_unit = minutes
```

Another strategy:

```text
Failed payment follow-up:
delay_enabled = true
time_value = 10
time_unit = minutes
```

The exact delay should depend on the business, event type, product, checkout flow, and urgency.

---

## When an Immediate or Very Short Delay May Be Appropriate

There are situations where calling quickly may be useful.

A quick call may be appropriate when the event suggests the customer needs immediate help.

Examples:

```text
The customer appears to have entered incorrect information.
The customer repeatedly fails checkout.
The customer is attempting a high-value purchase.
The customer has a known history of needing phone assistance.
The payment failure reason suggests confusion or correctable input.
The customer requested help or a callback.
The event is urgent and customer assistance is likely beneficial.
```

In these cases, a short delay or even immediate call may be reasonable, but the MCP should still think carefully about whether the call will help or interrupt.

The instructions should also make the agent’s opening gentle and helpful.

Example:

```markdown
# Opening
- Politely explain that the call is to help if the customer had trouble completing checkout.
- Do not imply the customer did anything wrong.
- Ask whether now is a good time before discussing details.
- If the customer says they are still checking out or do not want help, politely end the call.
```

---

## Choosing the Delay Time Period

The delay time period should be based on the likely customer behavior after the event.

Questions the MCP should consider:

1. Is the customer likely still in checkout?
2. Is the event a soft decline, hard decline, pending sale, failed sale, trial expiration, or renewal issue?
3. Is the customer likely to retry payment without assistance?
4. Is the product high enough value to justify fast outreach?
5. Is the call more likely to help or disturb the customer?
6. Would an email or SMS-style workflow be less intrusive before a phone call?
7. Is this an upsell, checkout, subscription renewal, trial expiration, or post-purchase event?
8. Does the customer’s previous behavior suggest phone assistance is welcome?
9. Are there legal, compliance, or quiet-hour concerns?
10. Should the first call attempt happen minutes later, hours later, or the next business day?

A delay should not be copied blindly from examples.

The MCP should recommend a delay that matches the use case.

---

## Example Delay Strategies

| Scenario | Delay Guidance | Reason |
|---|---|---|
| Pending checkout | Usually short delay, such as several minutes. | Customer may still complete checkout without help. |
| Failed card decline | Short-to-moderate delay. | Customer may retry with another card or fix billing info. |
| Repeated checkout failures | Shorter delay may be justified. | Customer may be stuck and need assistance. |
| High-value failed sale | Shorter delay may be justified. | Recovery value may justify faster outreach. |
| Subscription renewal failure | Longer delay may be acceptable. | Renewal recovery is important but usually less immediate than active checkout. |
| Trial expiration failure | Moderate delay may be appropriate. | Customer may need assistance but may not be actively checking out. |
| Shipping/delivery event | Delay depends on event. | Some events require immediate support; others are better as later follow-up. |
| Post-purchase satisfaction | Longer delay. | Customer needs time to receive or use product. |

---

## Filters Are Still Checked After the Delay

Delay does not replace filters.

For outbound account-event AI Voice Agents, filters are evaluated after the delay has expired.

This means that even if an event initially triggers the AI Voice Agent, the call should only proceed after the delay if the item still passes the configured filters.

The filter checks can include:

- Event filters
- Status filters
- Campaign filters
- Metadata filters
- Customer filters
- Call limits
- Active window checks
- Filter Function result

The filter Function must still return:

```javascript
callback(null, 'pass');
```

for the call to proceed.

If the filter Function returns:

```javascript
callback(null, 'fail');
```

the outbound call should not happen, even after the delay has expired.

---

## Why Post-Delay Filtering Matters

Post-delay filtering prevents stale or unnecessary calls.

Example:

```text
Customer has failed checkout event
  ↓
AI Voice Agent waits 10 minutes
  ↓
Customer successfully completes checkout during the delay
  ↓
Filters are checked again after delay
  ↓
Sale no longer qualifies
  ↓
AI Voice Agent should not call
```

Another example:

```text
Subscription renewal fails
  ↓
AI Voice Agent waits 30 minutes
  ↓
Customer updates payment method and renewal succeeds
  ↓
Filter Function checks current state
  ↓
Function returns fail
  ↓
No unnecessary recovery call is made
```

This is critical because the customer’s situation may change during the delay period.

---

## Filter Function Design for Delayed Calls

When a delayed outbound call uses a filter Function, the Function should check the current state of the item, not only the original event state.

Good filter Function logic:

```text
Pass only if the sale is still pending or failed.
Pass only if the subscription renewal is still failed.
Pass only if the customer has not already completed payment.
Pass only if the customer has not opted out.
Pass only if no recent successful call or recovery happened.
Fail if the issue has already been resolved.
```

Example:

```javascript
exports.handler = async function(event, context, callback) {
  const sale = event?.data?.item_details || {};

  if (sale.status === 'paid' || sale.status === 'complete') {
    return callback(null, 'fail');
  }

  if (sale.metadata?.ai_voice_recovery_completed === 'true') {
    return callback(null, 'fail');
  }

  if (!sale.customer?.phone) {
    return callback(null, 'fail');
  }

  return callback(null, 'pass');
};
```

The exact field names should be based on the example input data for the relevant item type.

---

## Customer-Friendly Agent Instructions for Delayed Checkout Calls

When calling after a checkout-related delay, the agent instructions should be respectful and non-disruptive.

Recommended instruction language:

```markdown
# Checkout Timing and Customer Respect
- This call may occur shortly after the customer attempted checkout.
- The customer may still be completing checkout or may have already resolved the issue.
- Open gently and position the call as optional assistance.
- Do not pressure the customer.
- Ask whether now is a good time.
- If the customer says they are still checking out, already completed the order, or does not want help, politely acknowledge and end the call.
- Do not imply that the customer made a mistake unless the data clearly shows incorrect information and the wording is framed as helpful assistance.
```

Example opening:

```markdown
# Opening
- Say: "Hi, this is the support team calling because it looked like you may have had trouble completing checkout. I just wanted to see if you wanted help, but if you are still working on it or already finished, no problem."
```

---

## MCP Guidance

When creating or editing an outbound AI Voice Agent, MCP should explicitly consider delay settings.

The MCP should ask or decide:

1. Could the customer still be attempting checkout when the event fires?
2. Would calling immediately help or interrupt?
3. Is the trigger event a checkout, failed payment, pending sale, renewal, trial, shipping, or follow-up event?
4. What delay gives the customer enough time to self-resolve?
5. Is the delay short enough to still recover the opportunity?
6. Should the filter Function check whether the issue was resolved during the delay?
7. Should the agent opening acknowledge that the customer may already have resolved the issue?
8. Should the agent be instructed to end quickly if the customer is busy, still checking out, or uninterested?

Important rule:

```text
Delay strategy is part of customer experience design, not just a technical trigger setting.
```


# Canonical AI Voice Agent Data Model: Filter Function vs Pre-Agent Function vs Instruction Compile Data

AI Voice Agents can use three different kinds of dynamic logic/data around a call:

1. **Filter Function** — decides whether an outbound call should happen.
2. **Pre-Agent Function** — runs before the AI Voice Agent instructions are compiled and returns custom data for Handlebars.
3. **AI Voice Agent instruction compile data** — the built-in data RevCent provides when compiling `settings.instructions.markdown` for the specific call.

These are related, but they are not the same thing.

| Concept | When It Runs | Main Purpose | Input Data Source | Output / Usage |
|---|---|---|---|---|
| Filter Function | Before an outbound call is allowed to run. | Decide whether the AI Voice Agent should call the item/customer. | Item-specific filter body based on `item_type`. | Must return `pass` or `fail`. |
| Pre-Agent Function | Before the AI Voice Agent instructions are compiled. | Generate custom dynamic content for Handlebars in the agent instructions. | Pre-agent body based on outbound/inbound context. | Response becomes available to instructions as `pre_agent_function`. |
| Instruction Compile Data | During Handlebars compilation before the call starts. | Provide built-in call, item, customer, and context data to the instructions. | AI Voice Agent input-data body based on outbound/inbound context. | Used directly in `settings.instructions.markdown`. |
| Function Triggered During Instructions | During the live call, if `TriggerFunction` system action is enabled. | Run custom logic during the conversation. | Arguments generated by the AI during the live call. | Function result is used during the conversation. |

The MCP must not mix these up.

---

## Simple Difference

```text
Filter Function = Should this outbound call happen?
Pre-Agent Function = What extra custom data should be injected into the instructions before the call?
Instruction Compile Data = What built-in RevCent data is available to Handlebars when the instructions compile?
TriggerFunction = What custom logic can the AI run during the live call?
```

---

---

# Detailed Filter, Pre-Agent, Customer, and Snippet Behavior

This section is especially important for MCP/API clients that need to create or edit AI Voice Agents correctly.

The AI Voice Agent system has four separate data/function concepts that must not be confused:

```text
Filter Function
Pre-Agent Function
Instruction input_data / Handlebars compile data
AI Voice Snippets
```

---

## Detailed Filter Function `pass` / `fail` Behavior

A filter Function is a gatekeeper for outbound AI Voice Agent calls.

It answers one question:

```text
Should this outbound AI Voice Agent call run for this item?
```

The filter Function receives item-specific data for the event or on-demand item, based on the triggering `item_type`.

Example data URL format:

```text
https://revcent.com/documentation/files/function/event/filter/[item_type].json
```

Examples:

```text
https://revcent.com/documentation/files/function/event/filter/customer.json
https://revcent.com/documentation/files/function/event/filter/sale.json
https://revcent.com/documentation/files/function/event/filter/shipping.json
https://revcent.com/documentation/files/function/event/filter/subscription.json
https://revcent.com/documentation/files/function/event/filter/subscription_renewal.json
https://revcent.com/documentation/files/function/event/filter/chargeback.json
https://revcent.com/documentation/files/function/event/filter/fraud_detection.json
```

The Function must return one of two exact single-term results:

```javascript
callback(null, 'pass');
```

or:

```javascript
callback(null, 'fail');
```

Meaning:

| Return | Meaning | Result |
|---|---|---|
| `pass` | The item passes the filter. | The AI Voice Agent call is allowed to run. |
| `fail` | The item fails the filter. | The AI Voice Agent call is blocked/skipped. |

Important:

```text
Default behavior is pass.
```

That means if the Function is not present, or if the filtering configuration does not block the item, the outbound call may proceed according to the rest of the agent trigger settings.

However, if a filter Function is used, the MCP should ensure the Function explicitly returns `pass` or `fail`.

---

## Filter Function Return Rules

A filter Function should not return:

```javascript
callback(null, true);
callback(null, false);
callback(null, { result: 'pass' });
callback(null, { status: 'fail' });
callback(null, 'approved');
callback(null, 'blocked');
```

Correct:

```javascript
callback(null, 'pass');
```

Correct:

```javascript
callback(null, 'fail');
```

The return must be a single term.

The MCP should write filter Functions so all code paths end in either `pass` or `fail`.

Example:

```javascript
exports.handler = async function(event, context, callback) {
  const item = event?.data?.item_details || {};

  if (item.metadata?.do_not_call === 'true') {
    return callback(null, 'fail');
  }

  if (item.customer?.phone_opt_out === true) {
    return callback(null, 'fail');
  }

  return callback(null, 'pass');
};
```

---

## When to Return `pass`

Return `pass` when the item is eligible for the outbound call.

Examples:

```text
Sale is still pending or recoverable.
Customer has not opted out.
Customer has a valid phone number.
Shipment event is important enough for a call.
Subscription renewal is still failed/overdue.
Customer is in the right campaign or shop.
Chargeback risk requires proactive outreach.
```

Example:

```javascript
if (item.status === 'pending' && item.customer?.phone) {
  return callback(null, 'pass');
}
```

---

## When to Return `fail`

Return `fail` when the call should not happen.

Examples:

```text
Customer opted out.
Customer has no usable phone number.
Customer is in a suppression group.
Sale is already paid or no longer recoverable.
Shipment is not customer-impacting.
Subscription was already renewed.
Customer has already been called enough times.
Customer is not in the correct campaign/shop/brand.
The item does not meet value or priority thresholds.
```

Example:

```javascript
if (!item.customer?.phone) {
  return callback(null, 'fail');
}
```

---

## Filter Functions Are for Eligibility, Not Agent Personalization

A filter Function is not the right place to generate dynamic call instructions.

Use a filter Function for:

```text
Should the call run?
```

Use a pre-agent Function for:

```text
What extra custom data should be available when compiling the instructions?
```

Use `TriggerFunction` for:

```text
What custom logic should the AI run during the live conversation?
```

---

# Detailed Pre-Agent Function Behavior

A pre-agent Function runs immediately before the AI Voice Agent instructions are compiled.

It receives call/item context and returns JSON data that becomes available to the instruction compiler.

A pre-agent Function is useful when the agent needs custom dynamic data that is not already available in the built-in instruction input data.

Examples:

```text
Brand name based on campaign
Custom offer based on customer value
Product list to mention during the call
Refund rules from an external system
CRM account status
Risk classification
Support priority
Approved talking points
Do-not-say instructions
```

---

## Pre-Agent Function Input Data URLs

For outbound calls triggered by account event or api_direct/on-demand, pre-agent Function input data uses this URL format:

```text
https://revcent.com/documentation/files/function/event/pre_agent/outbound/[item_type].json
```

Examples:

```text
https://revcent.com/documentation/files/function/event/pre_agent/outbound/customer.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/sale.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/shipping.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/subscription.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/subscription_renewal.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/chargeback.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/fraud_detection.json
```

For inbound calls, the pre-agent input data depends on whether the inbound caller phone number matches an existing customer.

Inbound with customer match:

```text
https://revcent.com/documentation/files/function/event/pre_agent/inbound/customer_match.json
```

Inbound with no customer match:

```text
https://revcent.com/documentation/files/function/event/pre_agent/inbound/no_customer_match.json
```

---

## What a Pre-Agent Function Should Return

A pre-agent Function should return a plain JSON object.

Example:

```javascript
callback(null, {
  company_name: 'Acme Inc.',
  allow_full_refunds: false,
  offer_allowed: true,
  offer_text: 'Free shipping is available if the customer completes the order today.',
  product_list: [
    {
      name: 'Product A',
      price: 29.99
    },
    {
      name: 'Product B',
      price: 49.99
    }
  ],
  support_priority: 'high'
});
```

The pre-agent response should be:

- JSON serializable
- Structured
- Predictable
- Safe to inject into instructions
- Specific to the call
- Free of secrets or private internal credentials
- Written so the instruction document can reference known paths

Avoid returning unclear freeform text that gives the AI unsafe latitude.

Poor return:

```javascript
callback(null, {
  text: 'Say whatever you need to make them buy.'
});
```

Better return:

```javascript
callback(null, {
  offer_allowed: true,
  approved_offer_name: 'Free Shipping Recovery Offer',
  approved_offer_terms: 'Free standard shipping if the customer completes payment today.',
  max_discount_percent: 0,
  must_not_offer: [
    'Cash refund',
    'Unapproved discount',
    'Guaranteed delivery date'
  ]
});
```

---

## How Pre-Agent Function Data Appears in Instruction Compile Data

When a pre-agent Function returns a valid JSON object, RevCent makes it available to the AI Voice Agent instruction compiler under:

```text
pre_agent_function
```

The structure is:

```json
{
  "pre_agent_function": {
    "has_response": true,
    "response": {
      "company_name": "Acme Inc.",
      "allow_full_refunds": false
    }
  }
}
```

Use this in Handlebars as:

```handlebars
{{pre_agent_function.response.company_name}}
```

or:

```handlebars
{{#if pre_agent_function.response.allow_full_refunds}}
- The agent may offer a full refund if the customer qualifies under the refund rules.
{{else}}
- The agent must not offer a full refund.
{{/if}}
```

Important:

```text
Access returned fields through pre_agent_function.response.*
```

Do not assume the returned values are at the top level.

Wrong:

```handlebars
{{company_name}}
```

Correct:

```handlebars
{{pre_agent_function.response.company_name}}
```

---

## Guarding Pre-Agent Function References

The MCP should use guards around pre-agent data because the Function may not run, may fail, or may return no usable data.

Recommended:

```handlebars
{{#if pre_agent_function.has_response}}
Use this custom context:
{{{toString pre_agent_function.response}}}
{{/if}}
```

For individual fields:

```handlebars
{{#if pre_agent_function.response.company_name}}
- Identify as {{pre_agent_function.response.company_name}} customer support.
{{else}}
- Identify as customer support.
{{/if}}
```

For JSON arrays or objects, use triple braces with `toString`:

```handlebars
# Available Products
{{{toString pre_agent_function.response.product_list}}}
```

---

## Good Pre-Agent Function Use Cases

Use a pre-agent Function when the instructions need call-specific content before the call begins.

Examples:

```text
Determine brand name from campaign.
Generate an approved offer from external CRM data.
Create a product list for a sales agent.
Return refund/cancellation rules for this customer.
Summarize customer risk or support priority.
Pull external subscription entitlement data.
Generate a personalized call objective.
Return internal escalation rules based on customer status.
```

A pre-agent Function is often better than `TriggerFunction` when the data is needed before the first words of the call.

---

## Pre-Agent Function vs AI Voice Snippets

Pre-agent Functions and AI Voice Snippets are different.

| Concept | Purpose |
|---|---|
| Pre-Agent Function | Generates dynamic JSON data before the call based on the call/item context. |
| AI Voice Snippet | Reusable instruction content that can be compiled and inserted into the main instructions. |

A pre-agent Function is best for data.

A snippet is best for reusable instruction text.

They can work together.

Example:

```handlebars
{{snippets.card_guidelines}}

{{#if pre_agent_function.response.company_name}}
- Brand voice: represent {{pre_agent_function.response.company_name}}.
{{/if}}
```

---

# Outbound Calls Always Include a Top-Level `customer` Object

For outbound AI Voice Agent calls, the instruction compile input data will always include a top-level `customer` object outside of the `item` object.

This is important for Handlebars safety and consistency.

The MCP should prefer:

```handlebars
{{customer.first_name}}
```

instead of trying to branch based on the outbound item type.

Do not require different customer paths like:

```handlebars
{{item.item_details.first_name}}
```

for `customer` item type, or:

```handlebars
{{item.item_details.customer.first_name}}
```

for non-customer item types.

For outbound calls, use the top-level customer object:

```handlebars
{{#if customer.first_name}}
- Address the customer as {{customer.first_name}}.
{{else}}
- Use a friendly generic greeting.
{{/if}}
```

This allows one instruction pattern to work across outbound calls for different item types.

---

## Why the Top-Level Customer Object Matters

Outbound calls can be triggered by many item types:

```text
customer
sale
shipping
subscription
subscription_renewal
chargeback
fraud_detection
```

The customer may live in different places inside each item’s raw details.

Examples:

```text
customer item_type:
item.item_details.first_name
```

```text
sale item_type:
item.item_details.customer.first_name
```

```text
shipping item_type:
item.item_details.customer.first_name
```

But RevCent provides a normalized top-level `customer` object for outbound instruction compilation.

Therefore, the MCP should write outbound instructions against:

```text
customer.first_name
customer.last_name
customer.email
customer.phone
customer.id
customer.verified
```

This keeps instructions cleaner and safer.

---

## Outbound Instruction Compile Data URLs

Outbound call instruction compile data examples use:

```text
https://revcent.com/documentation/files/ai_voice_agent/outbound/[item_type].json
```

Examples:

```text
https://revcent.com/documentation/files/ai_voice_agent/outbound/customer.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/sale.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/shipping.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/subscription.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/subscription_renewal.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/chargeback.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/fraud_detection.json
```

These are the correct examples for AI Voice Agent outbound instruction compile data.

Do not use Function account-event body URLs as outbound instruction compile-data examples.

---

# AI Voice Snippets

AI Voice Snippets are reusable pieces of instruction content that can be compiled and inserted into the main AI Voice Agent instructions.

The compiled snippets are available to the main instruction document through the `snippets` object.

Example input data structure:

```json
{
  "snippets": {
    "card_guidelines": "Do not interrupt if the caller is providing card information."
  }
}
```

Reference a snippet in the main instructions:

```handlebars
{{snippets.card_guidelines}}
```

Snippets are useful for reusable instruction blocks such as:

- Card handling rules
- Refund policy
- Verification rules
- Transfer rules
- Tone and compliance guidelines
- Subscription cancellation rules
- Chargeback escalation rules
- Shipping support rules
- Disclosure language
- End-call behavior

---

## Snippets Are Instruction Text, Not Data Fetching

AI Voice Snippets should be treated as reusable instruction content.

They should not be used as a replacement for:

- Pre-agent Functions
- Filter Functions
- System actions
- TriggerFunction
- Data retrieval operations

Use snippets when the same instruction section should be reused across multiple AI Voice Agents.

Use pre-agent Functions when dynamic data must be generated for a specific call.

---

## Snippet and Pre-Agent Function Example

Example main instruction pattern:

```handlebars
# Card Handling Rules
{{snippets.card_guidelines}}

# Brand Context
{{#if pre_agent_function.response.company_name}}
- Identify as {{pre_agent_function.response.company_name}}.
{{else}}
- Identify as customer support.
{{/if}}

# Product List
{{#if pre_agent_function.response.product_list}}
{{{toString pre_agent_function.response.product_list}}}
{{/if}}
```

This combines:

```text
Reusable rules from snippets
+
Dynamic call-specific data from pre_agent_function.response
```

---

# MCP Guidance for Data-Safe Instruction Writing

When writing AI Voice Agent instructions, MCP should:

1. Use top-level `customer.*` fields for outbound customer personalization.
2. Use `item.*` fields for the triggering item context.
3. Use `pre_agent_function.response.*` for pre-agent Function return values.
4. Use `snippets.*` for reusable compiled snippet content.
5. Use `{{#if ...}}` guards around optional data.
6. Use `{{{toString ...}}}` for objects and arrays.
7. Avoid referencing raw nested customer paths inside `item.item_details` when top-level `customer` is available.
8. Avoid using Function account-event body URLs as AI Voice Agent instruction compile-data examples.
9. Keep filter Functions limited to `pass` / `fail` eligibility decisions.
10. Keep pre-agent Functions focused on structured JSON data for instruction compilation.

# Filter Functions

A filter Function is used to decide whether an outbound AI Voice Agent call should proceed.

A filter Function receives data specific to the `item_type` that triggered the AI Voice Agent.

For AI Voice Agent filter Functions, the example input data for each item type follows this URL format:

```text
https://revcent.com/documentation/files/function/event/filter/[item_type].json
```

Examples:

```text
https://revcent.com/documentation/files/function/event/filter/customer.json
https://revcent.com/documentation/files/function/event/filter/sale.json
https://revcent.com/documentation/files/function/event/filter/shipping.json
https://revcent.com/documentation/files/function/event/filter/subscription.json
https://revcent.com/documentation/files/function/event/filter/subscription_renewal.json
https://revcent.com/documentation/files/function/event/filter/chargeback.json
https://revcent.com/documentation/files/function/event/filter/fraud_detection.json
```

The filter Function body is based on the item that would trigger or receive the outbound call.

Examples:

```text
Outbound call triggered by sale item
  ↓
Filter Function receives sale-specific body
  ↓
Function returns pass or fail
```

```text
Outbound call triggered by shipping item
  ↓
Filter Function receives shipping-specific body
  ↓
Function returns pass or fail
```

---

## Filter Function Response

A filter Function should return either:

```javascript
callback(null, 'pass')
```

or:

```javascript
callback(null, 'fail')
```

Meaning:

| Response | Meaning |
|---|---|
| `pass` | The AI Voice Agent may proceed with the outbound call. |
| `fail` | The AI Voice Agent should not proceed with the outbound call. |

A filter Function is mostly used to save cost, reduce unnecessary calls, and prevent calls that should not happen.

Use filter Functions for questions like:

```text
Should this sale receive an outbound call?
Is this customer eligible to be called?
Is this shipping event worth calling about?
Is this renewal recoverable?
Is this customer suppressed or opted out?
Is this item high value enough to call?
```

---

## Filter Function Is Not for Instruction Content

A filter Function should not be treated as a way to generate Handlebars content for the AI Voice Agent instructions.

Use a filter Function to decide:

```text
call or do not call
```

Use a pre-agent Function to generate:

```text
custom instruction content
```

---

# Pre-Agent Functions

A pre-agent Function runs before the AI Voice Agent instructions are compiled.

Its purpose is to generate custom content that can be used in the AI Voice Agent instructions through Handlebars.

A pre-agent Function is especially useful when the agent needs business-specific context that RevCent’s built-in compile data does not already provide.

Examples:

```json
{
  "offer_allowed": true,
  "offer_text": "Offer free shipping if the customer completes payment today.",
  "support_priority": "high",
  "recommended_script": "Mention the customer is eligible for priority support."
}
```

The pre-agent Function response can then be used in instructions through the `pre_agent_function` object.

Example Handlebars:

```handlebars
{{#if pre_agent_function.offer_allowed}}
Offer the customer this approved offer: {{pre_agent_function.response.offer_text}}
{{/if}}
```

---

## Outbound Pre-Agent Function Input Data

A pre-agent Function fired on an outbound call can happen when the outbound call is triggered by:

```text
account_event
api_direct / on-demand
```

For outbound calls, the pre-agent Function input data uses this URL format:

```text
https://revcent.com/documentation/files/function/event/pre_agent/outbound/[item_type].json
```

Examples:

```text
https://revcent.com/documentation/files/function/event/pre_agent/outbound/customer.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/sale.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/shipping.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/subscription.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/subscription_renewal.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/chargeback.json
https://revcent.com/documentation/files/function/event/pre_agent/outbound/fraud_detection.json
```

The `[item_type]` is the item type that triggered or was supplied to the outbound call.

Examples:

```text
Outbound on-demand call for sale
  ↓
Pre-agent Function input:
https://revcent.com/documentation/files/function/event/pre_agent/outbound/sale.json
```

```text
Outbound account-event call for shipping
  ↓
Pre-agent Function input:
https://revcent.com/documentation/files/function/event/pre_agent/outbound/shipping.json
```

---

## Inbound Pre-Agent Function Input Data

A pre-agent Function fired on an inbound call depends on whether the inbound caller number matches an existing customer.

If the inbound caller number matches an existing customer, the pre-agent Function input data uses this URL:

```text
https://revcent.com/documentation/files/function/event/pre_agent/inbound/customer_match.json
```

If the inbound caller number does not match an existing customer, the pre-agent Function input data uses this URL:

```text
https://revcent.com/documentation/files/function/event/pre_agent/inbound/no_customer_match.json
```

This distinction matters because an inbound call with a customer match has customer context available before the call, while an inbound call without a customer match does not.

---

## Pre-Agent Function Output

The pre-agent Function output should be designed as structured JSON that the instructions can safely use.

Good pre-agent output:

```json
{
  "eligible_for_offer": true,
  "offer_name": "Free Shipping Recovery Offer",
  "talking_points": [
    "The customer recently had a declined payment.",
    "The customer can complete the purchase today."
  ],
  "do_not_discuss": [
    "Internal fraud scores",
    "Internal risk rules"
  ]
}
```

Poor pre-agent output:

```json
{
  "text": "Say whatever you think will make them buy."
}
```

The pre-agent Function should produce clear, constrained, instruction-safe data.

---

# AI Voice Agent Instruction Compile Data

AI Voice Agent instructions are compiled with Handlebars before the call starts.

This compile-time data is separate from filter Function input and separate from pre-agent Function input.

The available instruction compile data depends on:

- Whether the call is inbound or outbound
- For outbound calls, the `item_type`
- For inbound calls, whether the caller number matched an existing customer
- Whether a pre-agent Function returned data
- Whether AI Voice Snippets are available

---

## Outbound Instruction Compile Data

For outbound calls triggered by either:

```text
account_event
api_direct / on-demand
```

the AI Voice Agent instruction compile data uses this URL format:

```text
https://revcent.com/documentation/files/ai_voice_agent/outbound/[item_type].json
```

Examples:

```text
https://revcent.com/documentation/files/ai_voice_agent/outbound/customer.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/sale.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/shipping.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/subscription.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/subscription_renewal.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/chargeback.json
https://revcent.com/documentation/files/ai_voice_agent/outbound/fraud_detection.json
```

This is the data available to `settings.instructions.markdown` when Handlebars compiles for that outbound call.

Example:

```text
Outbound call for sale
  ↓
Instruction compile data:
https://revcent.com/documentation/files/ai_voice_agent/outbound/sale.json
```

Important:

The outbound pre-agent Function input body and outbound AI Voice Agent instruction compile data are different schemas:

```text
Pre-agent outbound function body:
https://revcent.com/documentation/files/function/event/pre_agent/outbound/[item_type].json

Instruction compile data:
https://revcent.com/documentation/files/ai_voice_agent/outbound/[item_type].json
```

Do not assume paths are identical between them.

---

## Inbound Instruction Compile Data

For inbound calls, the AI Voice Agent instruction compile data depends on whether the inbound caller number matches an existing customer.

If the inbound caller number matches an existing customer, the instruction compile data uses this URL:

```text
https://revcent.com/documentation/files/ai_voice_agent/inbound/customer_match.json
```

If the inbound caller number does not match an existing customer, the instruction compile data uses this URL:

```text
https://revcent.com/documentation/files/ai_voice_agent/inbound/no_customer_match.json
```

This distinction is important for writing safe instructions.

For customer-match inbound calls, instructions may be able to reference matched customer context, but should still follow verification rules before discussing private account details.

For no-customer-match inbound calls, instructions should not assume a customer exists. The agent may need to use `SearchCustomers` if that system action is enabled and the caller provides identifying details.

---

## Inbound Pre-Agent vs Inbound Instruction Compile Data

Inbound pre-agent Function input files:

```text
https://revcent.com/documentation/files/function/event/pre_agent/inbound/customer_match.json
https://revcent.com/documentation/files/function/event/pre_agent/inbound/no_customer_match.json
```

Inbound AI Voice Agent instruction compile data files:

```text
https://revcent.com/documentation/files/ai_voice_agent/inbound/customer_match.json
https://revcent.com/documentation/files/ai_voice_agent/inbound/no_customer_match.json
```

Do not confuse these.

The pre-agent Function receives the pre-agent event body.

The AI Voice Agent instructions receive the AI Voice Agent compile data.

---

# Data Availability Decision Table

| Call Scenario | Filter Function Input | Pre-Agent Function Input | Instruction Compile Data |
|---|---|---|---|
| Outbound account-event call for `[item_type]` | `https://revcent.com/documentation/files/function/event/filter/[item_type].json` | `https://revcent.com/documentation/files/function/event/pre_agent/outbound/[item_type].json` | `https://revcent.com/documentation/files/ai_voice_agent/outbound/[item_type].json` |
| Outbound api_direct / on-demand call for `[item_type]` | `https://revcent.com/documentation/files/function/event/filter/[item_type].json` if a filter is used | `https://revcent.com/documentation/files/function/event/pre_agent/outbound/[item_type].json` | `https://revcent.com/documentation/files/ai_voice_agent/outbound/[item_type].json` |
| Inbound call with customer match | Not applicable | `https://revcent.com/documentation/files/function/event/pre_agent/inbound/customer_match.json` | `https://revcent.com/documentation/files/ai_voice_agent/inbound/customer_match.json` |
| Inbound call with no customer match | Not applicable | `https://revcent.com/documentation/files/function/event/pre_agent/inbound/no_customer_match.json` | `https://revcent.com/documentation/files/ai_voice_agent/inbound/no_customer_match.json` |

---

# Function Triggered During Agent Instructions

A Function triggered during agent instructions is different from both a filter Function and a pre-agent Function.

This pattern requires the `TriggerFunction` system action.

It runs during the live conversation when the AI decides, based on the instructions, that it needs to trigger a custom Function.

Use `TriggerFunction` for live-call needs such as:

- Look up external CRM data during the call
- Validate an external account number
- Generate a real-time offer
- Call an external eligibility API
- Calculate a custom discount
- Log a custom event to a third-party system
- Retrieve business-specific data not available in built-in RevCent actions

Do not use `TriggerFunction` when:

- The Function is only deciding whether the call should happen; use a filter Function.
- The Function should generate instruction content before the call; use a pre-agent Function.
- The data can be provided by built-in compile data or enabled system actions.
- The instructions do not clearly explain when to trigger the Function.

---

# MCP Rules for Writing Instructions With These Data Sources

When generating or editing `settings.instructions.markdown`, MCP should follow these rules:

1. Determine the call method: `inbound` or `outbound`.
2. For outbound calls, determine the trigger and `item_type`.
3. Use the correct outbound instruction compile data reference:
   ```text
   https://revcent.com/documentation/files/ai_voice_agent/outbound/[item_type].json
   ```
4. For inbound calls, determine whether the instructions should handle both customer-match and no-customer-match cases.
5. Use the correct inbound instruction compile data references:
   ```text
   https://revcent.com/documentation/files/ai_voice_agent/inbound/customer_match.json
   https://revcent.com/documentation/files/ai_voice_agent/inbound/no_customer_match.json
   ```
6. If a pre-agent Function is configured, use the correct pre-agent input reference for the call type.
7. Use `{{#if ...}}` guards around optional customer, item, and pre-agent data.
8. Do not reference item-specific fields unless they exist for the selected `item_type`.
9. Do not assume a caller is verified just because an inbound phone number matched a customer.
10. Include system actions only when the agent needs to retrieve or mutate data during the live call.
11. Use `TriggerFunction` only for live-call custom logic, not for filtering or pre-call instruction compilation.

---

## Safe Handlebars Pattern

Use guarded references:

```handlebars
{{#if customer}}
Customer context may be available, but verify the caller before discussing private account details.
{{/if}}

{{#if item}}
This outbound call is related to {{item.item_type}} {{item.item_id}}.
{{/if}}

{{#if pre_agent_function}}
Use the following approved custom context:
{{{toString pre_agent_function.response}}}
{{/if}}
```

Avoid unguarded assumptions:

```handlebars
Hi {{customer.first_name}}, I see your order failed.
```

unless the selected compile data guarantees those fields and the instructions still handle verification correctly.

# Function Patterns in AI Voice Agents

Use the canonical section above, **“Canonical AI Voice Agent Data Model: Filter Function vs Pre-Agent Function vs Instruction Compile Data,”** as the source of truth.

Summary:

```text
Filter Function = decides whether an outbound call should happen
Pre-Agent Function = generates custom data before instructions compile
Instruction Compile Data = built-in RevCent data used by Handlebars
TriggerFunction = custom Function triggered during the live call
```

Key example-data URLs:

```text
Filter Function input:
https://revcent.com/documentation/files/function/event/filter/[item_type].json

Outbound pre-agent Function input:
https://revcent.com/documentation/files/function/event/pre_agent/outbound/[item_type].json

Outbound instruction compile data:
https://revcent.com/documentation/files/ai_voice_agent/outbound/[item_type].json

Inbound pre-agent Function input with customer match:
https://revcent.com/documentation/files/function/event/pre_agent/inbound/customer_match.json

Inbound pre-agent Function input with no customer match:
https://revcent.com/documentation/files/function/event/pre_agent/inbound/no_customer_match.json

Inbound instruction compile data with customer match:
https://revcent.com/documentation/files/ai_voice_agent/inbound/customer_match.json

Inbound instruction compile data with no customer match:
https://revcent.com/documentation/files/ai_voice_agent/inbound/no_customer_match.json
```

# Output Schema

Successful response:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "ai_voice_agent_id": "XXXXXXXXXXXXXXXXXXXX",
  "result": "..."
}
```

---

# Edit Checklist

1. Confirm `ai_voice_agent_id`.
2. Retrieve the current agent before editing nested settings.
3. Disable before major edits.
4. Determine whether instructions need a targeted edit or a full rewrite.
5. Ask the user for the specific behavior change, purpose, nuances, call flow, allowed actions, prohibited actions, verification rules, and escalation rules.
6. Draft detailed revised `settings.instructions.markdown`; never replace instructions with minimal or generic Markdown.
7. Display the drafted revised instructions to the user for review before submitting the edit.
8. Include only fields you intend to change.
9. Preserve nested settings if submitting `settings`.
10. Confirm system actions and instructions match.
11. Keep system actions minimal.
12. Use strict instructions for payment/refund/card/sale/subscription actions.
13. Use active windows for outbound calls.
14. Use call limits.
15. For account-event outbound triggers, set `max_calls_per_item = 1`.
16. Use delay for customer-sensitive outbound calls.
17. Use filter Function for eligibility only.
18. Use pre-agent Function for instruction content only.
19. Use `TriggerFunction` only for live-call custom actions.
20. Test before re-enabling.


---

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