# RevCent AI Voice Snippets Overview This document gives a general overview of AI Voice Snippets in RevCent. AI Voice Snippets are reusable pieces of AI Voice Agent instruction content. They help businesses avoid copying the same instruction blocks into multiple AI Voice Agents and make it easier to update shared behavior in one place. Sources: - RevCent Knowledge Base: [AI Voice Agents — AI Voice Snippets](https://kb.revcent.com/en/tools/ai/voice-agents#ai-voice-snippets) - RevCent API/MCP operation schemas for `CreateAIVoiceSnippet` and `EditAIVoiceSnippet` --- ## What Is an AI Voice Snippet? An AI Voice Snippet is a reusable subset of AI Voice Agent instructions. Instead of writing the same instruction section inside every AI Voice Agent, a business can create a snippet once and reference it from one or more AI Voice Agent instruction documents. Example: ```text Create snippet: card_guidelines Use in agent instructions: {{snippets.card_guidelines}} ``` When the AI Voice Agent instructions are compiled for a call, the snippet reference is replaced with the compiled snippet content. --- ## Why AI Voice Snippets Exist AI Voice Agents often need repeated instruction sections. Examples: - Card collection rules - Refund policy - Subscription cancellation rules - Caller verification rules - Transfer/escalation rules - Tone and personality rules - Legal/compliance disclaimers - End-call rules - Chargeback escalation rules - Shipment support rules - Failed payment recovery rules - Human handoff instructions Without snippets, each AI Voice Agent would need its own copy of those rules. That creates maintenance problems: policy changes must be copied into many agents, some agents may be forgotten, and instructions can become inconsistent. AI Voice Snippets solve this by centralizing reusable instruction content. --- ## Core Benefit The core benefit is: ```text Write reusable AI Voice Agent instruction content once, then reuse it across multiple agents. ``` If the snippet is updated later, all main agent instructions that reference the snippet can compile with the updated snippet content. This is useful because AI Voice Agent behavior often evolves as businesses learn from real calls, AI model behavior changes, and policies improve. --- --- # When AI Voice Snippets Should Be Used AI Voice Snippets should be used intentionally. They are most useful when a RevCent user has **multiple AI Voice Agents** and certain shared instruction statements are used across those agents and changed frequently. Examples of shared instruction statements that may justify snippets: - Card collection rules used by many payment-related agents - Caller verification rules used by many inbound support agents - Transfer rules used by many agents - Refund policy language used by many support agents - Compliance/disclosure language used by many agents - Chargeback escalation rules used by many support or risk agents - Shipping support language used by many order-status agents The main reason to use snippets is maintenance. If a shared instruction block changes often and appears in many AI Voice Agents, a snippet can reduce repetitive editing and help keep behavior consistent. --- ## When Direct Agent Instruction Edits Are Better In many cases, it is better to modify the AI Voice Agent instructions directly instead of creating snippets. This is especially true when the user has fewer than about **5 AI Voice Agents**. For small AI Voice Agent setups, direct instruction edits are often better because: - The instructions are easier to read in one place. - There is less indirection. - The agent’s full behavior is easier to review. - There is less risk of a shared snippet changing multiple agents unexpectedly. - MCP clients and humans can understand the full agent behavior without resolving snippet references. - The user may not have enough repeated shared content to justify a snippet. Best practice: ```text If the user has fewer than 5 AI Voice Agents, prefer editing the AI Voice Agent instructions directly unless there is a clear repeated instruction block that changes often. ``` --- ## Practical Rule of Thumb Use a snippet when all of these are true: ```text The same instruction block is used by multiple AI Voice Agents. The shared instruction block is likely to change over time. The user wants one central place to maintain that shared behavior. The snippet will make the agents easier to maintain, not harder to understand. ``` Do not use a snippet when: ```text Only one AI Voice Agent needs the instruction. The user has only a few agents and direct edits are simpler. The instruction is highly specific to one agent. The snippet would hide important behavior from the main instruction document. The snippet is unlikely to be reused. The snippet adds indirection without reducing maintenance work. ``` --- ## Snippets Add Indirection A snippet reference like: ```handlebars {{snippets.card_guidelines}} ``` is concise, but it hides the actual instruction content from the main AI Voice Agent instruction document. This can be good when the snippet is truly shared and frequently updated. It can be bad when the user or MCP needs to review the full behavior of a single agent. For simple setups, direct instructions are usually clearer. --- ## Recommended Decision Before creating or relying on AI Voice Snippets, ask: ```text How many AI Voice Agents does the user have? How many agents will actually use this snippet? Will this shared text change often? Would direct instruction editing be clearer? Could a snippet edit accidentally affect agents that should behave differently? ``` If the answer is that the user has only one or a few agents, or the instruction is not frequently reused, direct instruction edits are usually better. # How Snippets Are Used in Agent Instructions AI Voice Snippets are accessed in the main AI Voice Agent instructions through the `snippets` object. Example: ```handlebars {{snippets.card_guidelines}} ``` If the enabled snippet named `card_guidelines` contains: ```markdown # Customer Card Guidelines - Be patient while the caller provides card information. - Do not interrupt the caller while they are reciting their card number. - Confirm before attempting a payment action. ``` then the main AI Voice Agent instructions can include: ```handlebars # Payment Handling {{snippets.card_guidelines}} ``` At compile time, the snippet content is inserted into the final instruction document provided to the AI. --- ## Snippet Names Become Handlebars Keys The snippet name is important because it becomes the key used inside the `snippets` object. Example: ```text Snippet name: card_guidelines ``` Usage: ```handlebars {{snippets.card_guidelines}} ``` This is why snippet names should be clear, stable, and safe for Handlebars access. Good snippet names: ```text card_guidelines refund_policy caller_verification transfer_rules subscription_cancellation chargeback_escalation shipping_support end_call_rules ``` Avoid vague names: ```text snippet rules test content voice ``` --- # Snippets Compile With Handlebars AI Voice Snippets compile like AI Voice Agent instructions. A snippet can contain Handlebars syntax and use the same call-specific input data available when compiling the AI Voice Agent instructions, except the `snippets` object itself. Available data can include: - `call_method` - `agent` - `item` - `customer` - `pre_agent_function` - Custom helpers such as `toString` and `ifEquals` Important: ```text The snippets object is only available in the main AI Voice Agent instructions, not inside individual snippet compilation. ``` This means a snippet should not reference another snippet using `{{snippets.other_snippet}}`. Do not create recursive or nested snippet dependencies. --- ## Customer Object in Snippets Snippets can safely reference the normalized `customer` object. Example: ```handlebars {{#if customer.verified}} - Address the customer by first name when appropriate: {{customer.first_name}}. {{else}} - Use a friendly generic greeting and do not assume the caller is an existing customer. {{/if}} ``` For outbound AI Voice Agent calls, RevCent provides customer details at the top-level `customer` object. Therefore, reusable outbound snippets should prefer: ```handlebars {{customer.first_name}} ``` instead of item-specific paths such as: ```handlebars {{item.item_details.first_name}} {{item.item_details.customer.first_name}} ``` --- ## Pre-Agent Function Data in Snippets Snippets can reference pre-agent Function output. Pre-agent Function data is accessed through: ```text pre_agent_function.response.* ``` Example: ```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 objects or arrays, use `toString` with triple curly braces: ```handlebars # Available Products {{{toString pre_agent_function.response.product_list}}} ``` Wrong: ```handlebars {{company_name}} {{pre_agent_function.company_name}} ``` Correct: ```handlebars {{pre_agent_function.response.company_name}} ``` --- # What Snippets Should Be Used For AI Voice Snippets are best for reusable instruction sections. ## Card Handling Rules ```markdown # Customer Card Guidelines - Be patient while the caller provides card information. - Do not interrupt the caller while they are reciting card details. - Only collect card information if the caller clearly agrees. - Do not repeat full card numbers back to the caller. ``` ## Verification Rules ```markdown # Verification Rules - Before discussing private account information, verify the caller using approved identifying details. - Do not reveal account details to an unverified caller. ``` ## Transfer Rules ```markdown # Transfer Rules - If the caller asks for a human, representative, supervisor, or manager, offer to transfer. - Do not argue with the caller about the transfer. ``` ## Refund Policy ```markdown # Refund Policy - Do not promise a refund unless the enabled system actions and business policy allow it. - If the caller threatens a chargeback, do not issue a refund automatically; follow escalation rules. ``` ## Subscription Cancellation Rules ```markdown # Subscription Cancellation Rules - If the customer asks to cancel, acknowledge the request calmly. - Ask one brief reason question if appropriate. - Follow the enabled system action rules. ``` ## Chargeback Escalation Rules ```markdown # Chargeback Escalation - If the caller says they will call their bank, dispute the charge, or file a chargeback, remain calm. - Do not accuse the caller. - Follow escalation rules and create a note if enabled. ``` --- # What Snippets Should Not Be Used For AI Voice Snippets should not replace the full AI Voice Agent instructions. A snippet should not usually define: - Entire conversation flow - Full agent role - Full system action strategy - Complete payment workflow - Full refund workflow - Full subscription workflow - All call boundaries for one agent Those belong in the main AI Voice Agent instructions. A snippet should be a reusable module. --- # Snippets vs Pre-Agent Functions AI Voice Snippets and pre-agent Functions serve different purposes. | Concept | Purpose | |---|---| | AI Voice Snippet | Reusable instruction text. | | Pre-Agent Function | Dynamic call-specific JSON data used during instruction compilation. | Use a snippet when the same instruction text should be reused. Use a pre-agent Function when the agent needs data calculated or retrieved for this specific call. They can work together. Example: ```handlebars # Brand Voice {{snippets.brand_voice_rules}} {{#if pre_agent_function.response.company_name}} - For this call, the brand is {{pre_agent_function.response.company_name}}. {{/if}} ``` --- # Snippets vs System Actions AI Voice Snippets do not give the AI permission to perform actions. System actions control what the AI can actually do during the live call. For example, a snippet may say: ```markdown - If the caller asks about their shipment, retrieve shipment details. ``` But the AI can only retrieve shipment details if the relevant system action, such as `GetShipment`, is enabled on the AI Voice Agent. Best practice: ```text Do not include snippet instructions that reference system actions unless the agents using the snippet are expected to have those system actions enabled. ``` --- # Best Practices ## Use Clear, Stable Names The snippet name is used in Handlebars. Good: ```text card_guidelines refund_policy caller_verification transfer_rules ``` Bad: ```text rules1 test stuff snippet ``` ## Prefer Direct Instructions for Small Setups If the user has fewer than about **5 AI Voice Agents**, direct AI Voice Agent instruction edits are usually better than snippets. Use snippets only when shared instruction statements are reused across multiple agents and are likely to change frequently. ## Keep Snippets Focused A snippet should usually cover one reusable topic. Good: ```text card_guidelines = card collection behavior refund_policy = refund boundaries transfer_rules = human transfer rules ``` Bad: ```text general_rules = card, refund, transfer, sales, shipping, subscriptions all mixed together ``` ## Use Handlebars Guards Use guards around optional data. ```handlebars {{#if customer.verified}} - Address the customer as {{customer.first_name}}. {{else}} - Use a generic greeting. {{/if}} ``` ## Do Not Reference `snippets` Inside Snippets The `snippets` object is only available in the main AI Voice Agent instructions. Do not do this inside a snippet: ```handlebars {{snippets.other_snippet}} ``` ## Review Agents After Updating a Shared Snippet If a snippet is used by many agents, updating it can affect all of them. After editing a shared snippet: - Review affected agents - Confirm instruction flow still makes sense - Confirm referenced system actions are enabled where needed - Test important call types --- # Example Snippet Library | Snippet Name | Purpose | |---|---| | `card_guidelines` | Rules for collecting card information. | | `caller_verification` | Identity verification before account details. | | `refund_policy` | Refund boundaries and escalation. | | `transfer_rules` | When to transfer to a human. | | `end_call_rules` | How and when to end the call. | | `chargeback_escalation` | How to respond to dispute threats. | | `subscription_cancellation` | Cancellation handling rules. | | `shipping_support` | Shipment/tracking support behavior. | | `payment_recovery_tone` | Tone for failed payment recovery. | | `compliance_disclosure` | Required disclosure language. | --- # Key Takeaways ```text AI Voice Snippets are reusable instruction modules. ``` ```text Enabled snippets compile into the main AI Voice Agent instructions through the snippets object. ``` ```handlebars {{snippets.card_guidelines}} ``` ```text Snippets can use Handlebars and call-specific data such as customer, item, and pre_agent_function. ``` ```text Snippets should not reference other snippets. ``` ```text Snippets do not enable system actions; they only provide instruction text. ``` ```text Shared snippets should be reviewed carefully because one snippet can affect many AI Voice Agents. Prefer direct AI Voice Agent instruction edits for small setups, especially when the user has fewer than 5 voice agents. ``` --- 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.