# Agentcreated Source: https://docs.oration.ai/api-reference/agentcreated /webhook-events/openapi-webhooks.json webhook agent.created Triggered when a new AI agent is created in the workspace # Agentupdated Source: https://docs.oration.ai/api-reference/agentupdated /webhook-events/openapi-webhooks.json webhook agent.updated Triggered when an AI agent is updated or modified or changed # Conversationanalysiscompleted Source: https://docs.oration.ai/api-reference/conversationanalysiscompleted /webhook-events/openapi-webhooks.json webhook conversation.analysisCompleted Triggered when a post call analysis is completed (e.g., user ends the conversation) # Conversationcompleted Source: https://docs.oration.ai/api-reference/conversationcompleted /webhook-events/openapi-webhooks.json webhook conversation.completed Triggered when a conversation is completed (e.g., user ends the conversation) # Conversationqacompleted Source: https://docs.oration.ai/api-reference/conversationqacompleted /webhook-events/openapi-webhooks.json webhook conversation.qaCompleted Triggered when a scorecard evaluation (QA) is completed for a conversation # Conversationstarted Source: https://docs.oration.ai/api-reference/conversationstarted /webhook-events/openapi-webhooks.json webhook conversation.started Triggered when a new conversation is initiated with an AI agent # Conversationuserjoined Source: https://docs.oration.ai/api-reference/conversationuserjoined /webhook-events/openapi-webhooks.json webhook conversation.userJoined Triggered when a user joins a conversation # Conversationuserleft Source: https://docs.oration.ai/api-reference/conversationuserleft /webhook-events/openapi-webhooks.json webhook conversation.userLeft Triggered when a user leaves a conversation # Get Conversation Source: https://docs.oration.ai/api-reference/endpoint/conversations/get GET /conversations/{conversationId} # Retrieving a Conversation This endpoint allows you to retrieve detailed information about a specific conversation using its unique identifier. ## Path Parameters | Parameter | Type | Description | | -------------- | ------------- | -------------------------------------------------------------- | | conversationId | string (UUID) | The unique identifier of the conversation you want to retrieve | ## Response Structure The response includes comprehensive details about the conversation, including: * Basic conversation details (ID, type, status) * Timing information (start time, end time) * Phone numbers and routing information * Post-call data and metadata * Dynamic variables used during the conversation ## Example Request Here's an example of how to retrieve a conversation: ```bash theme={null} curl --request GET \ --url https://www.oration.ai/api/v2/conversations/a7cc5115-fe5c-4a6a-3428-123b39ac8dd3 \ --header 'x-api-key: your-api-key-here' \ --header 'x-workspace-id: your-workspace-id-here' ``` ## Example Response ```json theme={null} { "id": "a7cc5115-fe5c-4a6a-3428-123b39ac8dd3", "phoneId": null, "agentId": "3e3132c1-700e-40e8-9b10-9fbd538f28c2", "workspaceId": "c9baa2e8-a75a-4203-8f64-45f232430926", "wsUrl": null, "llmUrl": null, "callStartTime": "2025-01-21T08:55:01.709Z", "callEndTime": "2025-01-21T08:55:55.333Z", "userJoinTime": null, "userLeaveTime": "2025-01-21T08:55:55.333Z", "customerId": "f8a70f62-d1ce-4860-8f1d-dce3ccdbbaab", "toPhoneNumber": "+911234123412", "fromPhoneNumber": null, "conversationStatus": "completed", "telephonyType": "outbound", "telephonyStatus": null, "endReason": "user_did_not_answer", "recordingStatus": null, "postCallNotes": null, "postCallCategory1": null, "postCallCategory2": null, "postCallCategory3": null, "postCallMetadata": null, "conversationType": "telephony", "dynamicVariables": "{\"customerName\":\"Alice Smith\",\"productName\":\"Gold Membership\"}", "summary": "", "createdAt": "2025-01-21T08:55:00.398Z", "updatedAt": "2025-01-21T08:55:00.398Z" } ``` ## Error Responses ### 404 Not Found ```json theme={null} { "message": "Conversation not found or access denied", "code": "NOT_FOUND", "data": { "code": "NOT_FOUND", "httpStatus": 404, "path": "workspaces.conversation.getById", "zodError": null } } ``` ### 401 Unauthorized ```json theme={null} { "message": "User Not Found", "code": "UNAUTHORIZED", "data": { "code": "UNAUTHORIZED", "httpStatus": 401, "path": "workspaces.conversation.getById", "zodError": null } } ``` ### Tips for Using the Get Conversation Endpoint 1. **Store Conversation IDs**: Always store the conversation IDs returned from the create conversation endpoint if you plan to retrieve them later. 2. **Error Handling**: Implement proper error handling for cases where the conversation might not exist or the API key is invalid. 3. **Timestamps**: All timestamp fields are returned in ISO 8601 format with UTC timezone. # Create Conversations Source: https://docs.oration.ai/api-reference/endpoint/conversations/post POST /conversations Creates conversations for chat, web, or telephony flows within a workspace. This endpoint supports batch creation and can optionally bypass a customer's do-not-disturb flag when `ignoreDND` is set to `true` for an individual conversation payload. # Create Conversations This endpoint allows you to create conversations with AI agents. ## Dynamic Variables Dynamic variables allow you to personalize your AI agent's responses for each conversation. They're a powerful way to make your conversations more relevant and context-aware. Here's how you can use them: ### How It Works 1. When defining your AI agent, you can include a `dynamicVariables` in your prompts using the `{{variableName}}` placeholder. 2. When creating a conversation, you can include those variables as a dictionary in the `dynamicVariables` field in your request body. 3. Each key-value pair in this object represents a variable that can be used by your AI agent during the conversation. 4. Your agent can then reference these variables to personalize its responses. ### Example Usage Here's an example of how to include dynamic variables when creating a conversation: ```json theme={null} { "conversations": [ { "agentId": "5e3832c1-700e-49e8-9b10-9fbd5f8f28c2", "conversationType": "telephony", "toPhoneNumber": "+1234567890", "dynamicVariables": { "customerName": "Alice Smith", "productName": "Gold Membership", } } ] } ``` In this example: * `customerName` could be used by the agent to greet the customer by name. * `productName` might be referenced when discussing the customer's current subscription. ## Rate Limiting The API has a rate limit of 20 concurrent calls per workspace. If you exceed this limit, the API will return a 429 error. The rate limit is enforced per workspace. If you need to increase the limit, please contact us. The endpoint throws a 429 error when the available slots are occupied by `active` or `dialing` conversations. ## Example Request Here's a simple example using cURL: ```bash theme={null} curl --request POST \ --url https://www.oration.ai/api/v2/conversations \ --header 'x-api-key: your-api-key-here' \ --header 'x-workspace-id: your-workspace-id-here' \ --data '{ "conversations": [ { "agentId": "5e3832c1-700e-49e8-9b10-9fbd5f8f28c2", "conversationType": "telephony", "toPhoneNumber": "+1234567890", "dynamicVariables": { "customerName": "Bob Johnson", "appointmentTime": "3:00 PM", "serviceType": "Annual Check-up" } } ] }' ``` This request will trigger a phone call to the specified number, and the AI agent will be able to use the provided dynamic variables to personalize the conversation. By leveraging dynamic variables, you can create more engaging and personalized AI-driven conversations that adapt to each unique interaction. ## Developer Recommendations When you are trying to make multiple calls using this API endpoint. You can use the following strategy to ensure maximum utilisation of the available concurrency. There are two simple rules to follow: 1. **Use Short Bursts**: If you need to make a lot of calls, consider making them in short bursts. 2. **Listen to the Rate Limit Headers**: Rather than sending a batch of arbitrary length, listen to the rate limit headers and adjust the length of calls to be made accordingly. ### Example Strategy In case you want to make 200 calls. Assuming your max concurrent calls is 20. 1. You can add 20 conversations in the first request. 2. Then wait for few seconds and make another request with another 20 conversations. Check the rate limit headers and adjust the length of calls to be made accordingly. 3. You can adjust the size of the batch based on the rate limit headers till you finish all the calls. 4. You can use the GET `/conversations` endpoint to check the status of the conversations. # Create Customers Source: https://docs.oration.ai/api-reference/endpoint/customers/post POST /customers/batch Queues a batch import job for customer records. Use `strategy=upsert` to merge existing customers by identifier or contact fields instead of inserting only new records. # Creating Customers This endpoint allows you to create customers. ## Request Body The request body should contain a `customers` array with the customer information you want to create. Each customer object in the array should include the following fields: | Field | Type | Required | Description | | ----------- | --------------------------------- | -------- | ------------------------------------------------------------------ | | name | string | No | The customer's full name | | phoneNumber | string | No | The customer's phone number in E.164 format (e.g., `+12345678901`) | | email | string | No | The customer's email address | | identifier | string | Yes | A unique identifier for the customer in your system | | metadata | object/string/number/boolean/null | No | Additional data about the customer that you want to store | | priority | integer | No | Calling priority for the customer. Default: 5. Ascending order. | You can use `priority` to control how the customers are picked during campaign runs. It is calculated in ascending order. **Lower the value, higher the priority. 0 is the highest priority.** In addition to the `customers` array, the request body can include the following top-level parameters: | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | strategy | string | No | The strategy to use when creating customers. Can be `upsert` or `insert`. Defaults to `insert` | | partial | boolean | No | When set to `true`, allows partial batch processing. Only valid when `strategy` is set to `insert`. This ensures customers without errors are still inserted even if others in the batch fail. | ## Response Structure The response includes the job ID. You can use this job ID to check the status of the job. | Field | Type | Description | | ----- | ------ | -------------------------------- | | jobId | string | The unique identifier of the job | # Get Job Status Source: https://docs.oration.ai/api-reference/endpoint/jobs/get GET /jobs/{id} Returns the current state of an asynchronous job such as a customer batch import. # Retrieving a Job Status This endpoint allows you to retrieve the status of a job. ## Path Parameters | Parameter | Type | Description | | --------- | ------------- | ----------------------------------------------------- | | id | string (UUID) | The unique identifier of the job you want to retrieve | ## Response Structure The response includes comprehensive details about the job, including: * Basic job details (ID, name, status) * Timing information (createdAt, updatedAt) * Job provider information * Workspace association * Error details (if applicable) The response object includes the following fields: | Field | Type | Description | | ------------- | ----------------- | ---------------------------------------------------------------------------------- | | id | string (UUID) | The unique identifier of the job | | createdAt | string (ISO date) | The timestamp when the job was created | | updatedAt | string (ISO date) | The timestamp when the job was last updated | | jobProviderId | string (UUID) | The identifier of the job provider that processed this job | | name | string | The name of the job | | status | string | The current status of the job (created, queued, active, success, failed, retrying) | | error | string or null | Error message if the job failed, null otherwise | | workspaceId | string (UUID) | The identifier of the workspace this job belongs to | # Introduction Source: https://docs.oration.ai/api-reference/introduction Welcome to the Oration AI API ## Welcome to Oration AI Oration AI provides a powerful API for creating and managing AI-powered conversations across various communication channels. Our API enables you to integrate advanced conversational AI capabilities into your applications, supporting chat, telephony, and web interfaces. ## Key Features Currently, Oration AI APIs only support creating conversations. * **Create conversations**: Easily initiate single or multiple AI-driven conversations with a single API call. * **Get conversation details**: Get the latest conversation status and details for any conversation. ## Getting Started To use the Oration AI API, you'll need: 1. An API Key 2. A Workspace ID These credentials should be included in the headers of your API requests: ```json theme={null} { "x-api-key": "your-api-key-here", "x-workspace-id": "your-workspace-id-here" } ``` ## Base URL All API requests should be made to: ``` https://www.oration.ai/api/v2 ``` ## Example Request Here's a simple example of creating a conversation using cURL: ```bash theme={null} curl --request POST \ --url https://www.oration.ai/api/v2/conversations \ --header 'x-api-key: your-api-key-here' \ --header 'x-workspace-id: your-workspace-id-here' \ --data '{ "conversations": [ { "agentId": "", "conversationType": "telephony", "toPhoneNumber": "+1234567890", "dynamicVariables": { "name": "John Doe" } } ] }' ``` ## What's Next? Explore our API endpoints to learn how to: * Create and manage conversations * Work with different conversation types * Handle API responses and errors We're excited to see what you'll build with Oration AI! # Agent Skills Source: https://docs.oration.ai/guides/agents/agent-skills Add reusable prompt blocks that empower your agents ## What are Agent Skills? Agent Skills are named “mini‑prompts” you can attach to an agent. Each skill contains a short piece of instruction (for example): > *Introduce yourself only once at the start of the call. If the customer says "hello" again mid‑call or re‑opens the conversation do not re‑introduce yourself. Simply continue from where the conversation left off.* Skills are **reusable** – the same skill can be attached to multiple agents. **Why use them?** * **Consistency** – All agents that need the same behavior share one skill, so you never forget to copy‑paste the prompt. * **Speed** – Add or change a behavior in seconds without editing the main system prompt. * **Safety** – Disable a skill temporarily without deleting it, letting you experiment safely. Agent Skills page ## Where do I find Agent Skills? * In the left navigation select **Agents → Skills**. * The page shows a list of existing skills grouped by the *skill pack* they belong to. > *(Screenshot above shows the Agent Skills page.)* ## Creating a New Skill ### Open the Create Form 1. Click **Create Skill** (top‑right button on the Skills page). ### Fill in the fields | Field | What to put | Tips | | ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- | | **Name** | A short, memorable title (e.g., *Refund‑Policy Reminder*). | Use title‑case, keep it under 30 chars. | | **Description** *(optional)* | One‑line summary that appears in the skill list. | Helpful for teammates. | | **Instructions** | The exact wording you want the agent to use. | Write in the voice you want the agent to speak. | | **Skill Pack** | Choose an existing pack **or** create a new one on the fly. | Packs are logical groups (e.g., *Customer Support*, *Sales*). | ### Save * Click **Create skill**. * The new skill appears in the list under the selected pack. ## Editing an Existing Skill 1. In the skill list click the three‑dot menu next to the skill you want to change. 2. Choose **Edit** – the **SkillEditDialog** opens. 3. Update **Name**, **Description**, or **Instructions** and hit **Save**. > **Tip:** The edit dialog also lets you move the skill to a different pack via the pack dropdown. ## Enabling / Disabling a Skill * Each **skill** has an on/off toggle in its card. * Turning a skill *off* removes its prompt from the agent’s system prompt while keeping the definition intact. ## Using Skill Packs * **Skill Packs** are purely organizational – they group related skills (e.g., *On‑boarding*, *Refund Handling*). * Packs have no enable/disable functionality; you manage visibility at the individual skill level. * Packs can be installed from pre‑built templates (provided by Oration) via the **Install Pack** button on the pack page. ## Best Practices for Non‑Developers | Recommendation | Why it helps | | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | | **Keep prompts short & clear** | Short prompts consume fewer tokens and are easier for the LLM to follow. | | **Use consistent naming** | E.g., *“FAQ – Billing”* → makes it easy to locate skills later. | | **Group related skills into a pack** | Keeps the UI tidy and helps you find skills quickly. | | **Test in preview before enabling** | Use the **Preview → Test Agent** button to see the skill in action before rolling it out. | | **Disable instead of delete** when experimenting | You can re‑enable later without recreating the text. | | **Include a description** | Helps teammates understand the purpose of each skill at a glance. | ## Previewing Skills in Action 1. From the **Agent Details** page click **Preview** → **Test Agent**. 2. Interact with the agent (type or speak). 3. Observe how the newly added skill influences the response. > *Screenshot of attaching a skill to an agent* Attach skill in agent If the behavior isn’t as expected, return to **Skills** → edit or toggle the skill and preview again. ## Frequently Asked Questions | Question | Answer | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | *Can a skill be used by multiple agents?* | Yes – skills are stored at the workspace level, so any agent in the same workspace can use them. | | *Do I need to restart the agent after adding a skill?* | No. Skills are injected into the system prompt each time a conversation starts, so changes take effect immediately. | | *What if I want to remove a skill temporarily?* | Use the skill toggle to **disable** it; the prompt will be omitted without losing the skill definition. | | *Is there a limit to how many skills I can have?* | Practically, the limit is the LLM token budget – keep the total prompt (base + skills) under the model’s max token count. | | *Can I import a ready‑made skill pack?* | Yes – click **Install Pack** on any *Skill Pack Template* (found under the **Templates** tab). | *** # Agents Source: https://docs.oration.ai/guides/agents/agents A guide to Agents, Knowledge Bases, and Tools in Oration AI ## Agents in Oration AI An agent in Oration AI is an intelligent assistant capable of handling customer conversations, answering questions, and performing tasks across voice, chat, and other channels. Powered by advanced speech recognition, language processing, and voice synthesis, agents can engage in human-like conversations, make and receive calls, integrate with existing systems, and manage complex workflows such as appointment scheduling and customer support Step by step, learn how to create and configure your first agent. Select **Agents** from side navigation and click **Create Agent** button on the right top corner. ## 1. Agent Details Agent Details The **Agent Details** tab is where you define the core identity and behavior of your agent. * **Name:** Set a clear, descriptive name for your agent. * **System Prompt:** Provide the main instructions and context for your agent’s role. This guides the agent’s responses and tone. * **Initiation Message:** The first message your agent delivers when a conversation starts. * **Initiation Type:** Choose who initiates the conversation (e.g., "AI Speaks First - Fixed"). * **End Call Enabled:** Toggle to allow the agent to end calls automatically. * **End Call Description:** Define the conditions under which the agent should terminate the call (e.g., "End the call when the customer shows an intent to finish the call"). Click **Update** to save your changes. *** ## 2. Agent Prompt Agent Prompt The **Agent Prompt** tab is an AI-powered prompt writing tool. Here, you can: * Write detailed instructions, context, and rules for your agent. * Use formatting tools to organize your prompt (headings, lists, bold, etc.). * Clearly separate role, context, and rules for better agent performance. * See all the editing activity (Delete, Insert and Update) by clicking `See What Changed` button * The `magic wand icon` on the top tool box will help you to make the prompt more intelligent with the AI assistance. Here is the guide to write prompt for your agent. **Tip:** Be explicit about what the agent should and shouldn’t do. Use examples and bullet points for clarity. ### Introduction to Dynamic Variables Dynamic variables are placeholders that allow your agent to personalize interactions by incorporating specific customer information into the conversation. They enable the agent to tailor responses based on individual customer data, enhancing the overall user experience. ### Purpose of Dynamic Variables The primary purpose of dynamic variables is to provide context-sensitive information during conversations. This can include customer names, account types, last purchase dates, and other relevant details that make interactions feel more personal and engaging. ### How to Use Dynamic Variables in Prompts To use dynamic variables in your agent's prompt, simply include them in double curly braces. For example, if you want to greet a customer by their name, you would use the variable `{{customerName}}`. ### Example Usage Here’s an example of how to incorporate dynamic variables into your agent's prompt: ```text theme={null} Hi {{customerName}}, welcome to our customer support team. How can I help you today? ``` *** ## 3. Configurations Agent Configurations The **Configurations** tab lets you fine-tune your agent’s behavior and environment. * **Backchannel & Filler Words:** Enable/disable natural conversation features like "uh-huh" or filler words. * **Background Voice Cancellation & Sound:** Improve audio quality or add ambient noise. * **Punctuation Boundaries:** Customize how the agent handles pauses and sentence endings. * **Emotion Detection:** Enable to detect the emotion from the callee's voice. * **Speech Normalization:** Convert numbers, currency, and dates into natural speech. * **Inactivity & Interruption Settings:** Control reminders, call timeouts, and interruption sensitivity. * **Inactivity Reminder Trigger Ms:** Time in milliseconds before an inactivity reminder is triggered * **Inactivity Reminder Max Count:** Maximum count of inactivity reminders * **Max Inactivity Duration Ms:** How long to wait before a call is automatically ended due to inactivity * **Boosted Keywords:** These are specialized terminology or uncommon proper nouns, you can provide those words to the model for it to incorporate as possible predictions. * **SIP Trunk Address:** Integrate with telephony systems. * **Language Settings:** Set default and supported languages for the agent. Click **Update** to apply your configuration changes. *** ## 4. Advanced Settings Advanced Settings The **Advanced Settings** tab provides deeper control over your agent’s technical setup: ### Update Transcription Settings * **Language:** Set the language for speech-to-text transcription. ### Update LLM Settings * **Temperature:** Adjust the creativity of the agent’s responses (higher = more creative).The range is from 0 to 1. Where a value closer to 1 will make the output more creative, and a value closer to 0 will make the output more focused and deterministic. * **Max Tokens:** Limit the length of responses. Use this to avoid excessively long responses but too few tokens can lead to stop abruptly. ### Update Speech Synthesis Settings * **Provider Voice Id:** Choose the voice for your agent from voice providers like Elevenlabs, Azzure etc. Paste the voice id from the provider. * **Voice Speed & Temperature:** Control the speed and expressiveness of speech. Advanced Settings ### Voice Mail Box Detection Settings * **Enable/Disable:** Turn on voicemail detection. * **Initial Detection Delay:** Set how long to wait before checking for voicemail. * **End Call Message:** Message to play before ending a call detected as voicemail. * **End Call Delay:** Time to wait before ending the call after voicemail detection. Advanced Settings ### Memory Settings Enable your agent to remember and reference customer information across conversations. * **Memory Enabled:** Toggle to capture and store customer information * **Memory Retention Duration:** Set how long memories should be retained (e.g., 7 days, 1 month, 1 year) * If left empty or set indefinitely, memories are stored **forever** * Memories are customer-specific and automatically expire after the retention period For detailed information on how to use Agent Memory, including how to view customer memories in the Customers section, see the [Agent Memory Guide](/guides/agents/memories). *** ## 5. Privacy Settings The **Privacy Settings** tab helps you control data collection and storage: * **Is Transcription Enabled:** Store or discard call transcripts. * **Is Audio Recording Enabled:** Store or discard audio recordings. * **Is Data Collection Enabled:** Control whether sensitive data (like phone numbers or emails) is collected. Toggle each setting as needed and click **Update** to save. *** ## 6. Post Call Analysis Post Call Analysis The **Post Call Analysis** tab lets you automate insights from every conversation. * **Is Enabled:** Toggle to run analysis after every call. * **Prompt:** Write a custom prompt to instruct the AI on what to analyze, or use **Generate Prompt** for suggestions. * **Schema:** Define the structure for extracting information (add properties, set types, and descriptions). * **Preview:** See how your schema will be applied. Click **Save** to activate post-call analysis. You can analyse the post call from the call history view, see the below video for more details. Steps to follow: 1. Go to the `History` view from and click on the call you want to analyse. 2. Click on the `Analysis` tab. Post Call Analysis ## 7. Preview and Share Before deploying your agent to real users, you can preview how it will perform in different scenarios. Oration AI provides several ways to test your agent. Post Call Analysis ### 1. Web Call * Click the **Preview** button at the top of the Agent Details page. * Select **Web Call** from the dropdown. * A web-based call interface will open, allowing you to interact with your agent with dynamic variables as if you were a customer calling in. * Speak and observe how the agent responds in real time. ### 2. Test Agent via Chat * In the **Preview** menu, choose **Test Agent**. * This opens a chat window where you can type messages to your agent. * Use this mode to quickly test conversation flows, responses, and logic without making a real call. ### 3. Make a Phone Call * This allows you to experience the full voice interaction over phone, including any telephony features like voicemail detection or call recording. * Make sure your agent is published and assigned to a phone number before testing this option. ### Share your Agent Once you're satisfied with your agent's performance in the preview, you're ready to share by clicking on `Sharing` button Post Call Analysis *** **Tip:** Use the preview options to test different scenarios, verify your agent’s responses, and fine-tune its configuration before going live. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Assists Source: https://docs.oration.ai/guides/agents/assists Let your voice agent ask a human colleague for help without transferring the call ## What are Assists? **Assists** let your voice agent pause a task and ask a human colleague for help — while staying on the line with the customer. Unlike a call transfer, the AI does not hand the conversation over. It creates a request, routes it through a contact-center queue, and keeps talking to the caller (or plays hold music) until a teammate accepts, rejects, or closes the request. Use Assists when the model can handle most of the call, but some steps need a person: looking up an account the AI cannot access, approving a refund, confirming a policy exception, or answering a question that is too sensitive to automate. Think of Assists as tools that call a human instead of an API. You configure them next to Tools in the dashboard, and the model invokes them the same way it invokes any other action. *** ## Assists vs Tools vs call transfer | | **Tools** | **Assists** | **Call transfer** | | ----------------------- | --------------------------------- | ------------------------------------------------- | ------------------------------------------ | | Who does the work | Your API or backend | A human on a contact-center queue | A human who takes the live call | | What the customer hears | The AI stays on the call | The AI stays on the call (or hold music) | The AI leaves; a person picks up | | When to use it | Lookups, updates, SMS, CRM writes | Judgement, systems the AI cannot reach, approvals | The caller must speak to a person directly | If the caller needs to *talk to* someone, use [call transfer](/guides/flows/nodes/transfer). If the AI only needs a colleague to *do something* in the background, use an Assist. *** ## How Assists are organized Assists follow the same hierarchy as Tools: * **Assist** — A named container (shown as **Assists** in the sidebar under **Tools**). It holds one or more actions. * **Action** — A single LLM-callable task, such as `lookup_order` or `approve_refund`. Name and description are what the model sees. Each action points at a contact-center **queue**. * **Instance** — One live request created when the model calls an action during a conversation. Instances show up in **History** and in the contact-center **Assists** inbox. You can clone an Assist or an action when you want a starting point instead of building from scratch. *** ## Prerequisites You will need at least one **queue** in the contact center before you add actions. Every action routes requests through a queue — without one, the add-action form cannot be submitted. Make sure the teammates who should handle requests are assigned to that queue and can open the contact-center **Assists** inbox. *** ## Create an Assist In the dashboard, go to **Tools → Assists**. Click **New Assist**. * **Name** — A short label your team will recognize (for example, `Order lookups` or `Billing exceptions`). * **Description** — What this Assist is for. This is for your team, not the model. Click **Create**. The new Assist appears on the list. Open it to add actions. Assist names must be unique in the workspace. If you see a duplicate-name error, pick a different name or clone the existing Assist instead. *** ## Add an action Open an Assist and click **Add Action**. Each action is advertised to the model as a tool. ### What the model sees | Field | What to put | Tips | | ----------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | **Name** | The tool name the LLM calls (for example, `lookup_order`). | Letters, digits, underscore, and hyphen only. Max 64 characters. Use `snake_case`. | | **Description** | When and why the model should call this action. | Be specific: “Use this when the customer asks for order status and you cannot find it in tools.” | | **Queue** | The contact-center queue that receives requests for this action. | Different actions on the same Assist can use different queues. | | **Assist reason description** | Guidance for the required `assistReason` argument. | Tell the model to summarize *what the human needs to do*, not the whole transcript. | | **Parameters schema** | Optional extra JSON Schema fields beyond `assistReason`. | Use this when the human needs structured data (order ID, refund amount). | | **Restricted system prompt** | Extra instructions used only while a human is waiting on the customer. | Keep this short. The model is collecting an answer, not continuing the original task. | ### How the request behaves | Field | Default | What it does | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **Interactive** | On | When on, the human agent can send free-text questions to the customer through the AI. | | **Blocking** | On | When on, the speech machine parks the caller (hold music) while the request is outstanding. Turn off if the AI should keep chatting. | | **Cancelable** | On | When on, the customer can refuse to continue and the model may cancel the request. Turn off for must-complete steps (compliance, identity). | | **Wait before execution** | On | Waits for the start message to finish speaking before the request is created. | Action names are function names. Spaces, punctuation, and emoji will be rejected. If two actions share a name inside the same Assist, creation fails. ### Optional parameters schema `assistReason` is always required. Add a parameters schema when the human needs extra fields the model can fill in: ```json theme={null} { "type": "object", "properties": { "orderId": { "type": "string", "description": "The customer's order ID, digits only." } }, "required": ["orderId"] } ``` The schema must be a JSON Schema object (`"type": "object"`). Invalid schemas are ignored at runtime, and the model will only send `assistReason`. *** ## Spoken copy and timeouts Every action has its own customer-facing lines and timers. Edit them from **Update Action**. Spoken copy is what the *caller* hears — never mention tool names or “assist request.” ### Spoken copy | Message | When the caller hears it | | ------------------------- | ------------------------------------------------------------------ | | **Start** | As soon as the model calls the action. | | **Queue delay** | Repeated while waiting for a teammate to pick up the request. | | **Working delay** | Repeated after a teammate is assigned and still working. | | **Success** | The teammate accepted the request. | | **Error / reject** | The teammate rejected the request. | | **Queue timeout** | Nobody picked up in time. | | **Working timeout** | The teammate did not finish in time. | | **Resume** | The customer answered a clarifying question from the human. | | **Human-agent close** | The teammate closed the request and handed control back to the AI. | | **User cancel** | The customer declined to continue. | | **Hold start / hold end** | The teammate put the caller on hold, then took them off. | | **Technical error** | The request failed for a system reason. | ### Timeouts (milliseconds) | Timeout | What it controls | | ------------------------- | ------------------------------------------------------------------------------------------ | | **Queue delay timeout** | How often the queue-delay line is spoken while unassigned. Default 10 seconds. | | **Working delay timeout** | How often the working-delay line is spoken after assignment. Default 10 seconds. | | **Queue timeout** | How long to wait in queue before giving up. Default 10 minutes. | | **Working timeout** | How long to wait after assignment before giving up. Default 10 minutes. | | **Failure timeout** | How long create / resume / cancel may wait before a technical failure. Default 10 minutes. | Match delay copy to the action. “I’m checking that order with a colleague” is clearer than a generic “please wait,” especially on blocking actions where the caller is on hold. *** ## What happens during a call When the conversation needs a person, the agent invokes the action (for example, `lookup_order`) and fills in `assistReason` plus any extra parameters. The AI speaks the start copy. If **Wait before execution** is on, the request is created only after that line finishes. A live instance is created and routed to the action’s queue. If **Blocking** is on, the caller hears hold music and delay copy until a teammate is assigned. In the contact-center **Assists** inbox, the request appears under **In-flight**. The teammate can accept, reject, send a clarifying question (if Interactive is on), put the caller on hold, or close the request. On accept, reject, timeout, cancel, or close, the AI speaks the matching line and continues the conversation with the outcome. ### Request statuses | Status | Meaning | | ---------------- | ------------------------------------------------------ | | Created / queued | Waiting for a teammate. | | Offered | At least one teammate has been offered the request. | | Working | A teammate is assigned and handling it. | | Completed | Accepted or closed by the human. | | Failed | Rejected, timed out, overflowed, or a technical error. | | Cancelled | The customer cancelled, or the conversation ended. | *** ## Handle requests in the contact center Human teammates work requests from **Contact Center → Assists**, not from the Tools page. * **In-flight** — Open requests that still need a person. * **Approved** — Requests that were accepted. * **Denied** — Requests that were rejected. Open a request to read the reason, the live transcript, and (when Interactive is on) send a question back to the customer. The voice agent speaks that question; the customer’s answer is returned to you. **Tools → Assists** is where you *configure* who the AI can ask and what they can ask for. **Contact Center → Assists** is where people *work* those live requests. *** ## Review stats and history Open an Assist to find three tabs: ### Actions Create, edit, clone, or delete the LLM-callable tasks on this Assist. ### Stats Counts for the selected date range (defaults to the last 30 days): * **Total** instances * **Completed** (with completion rate) * **Failed** * **Cancelled** * **Per action** breakdown (completed / total / failed) Use this tab to see which actions time out or get cancelled too often — usually a sign that copy, timeouts, or queue staffing need a change. ### History A paginated list of every instance: action name, status, end reason, and created time. Open a row to read the logs for that request. *** ## Edit, clone, and delete * **Edit** — Change the Assist name or description from the Assist page. Change an action’s queue from **Update Action**. * **Clone** — Duplicates the Assist and its actions. Use this to spin up a regional or language-specific variant. * **Delete** — Archives the Assist. Agents stop receiving its actions. Runtime history is kept. Deleting an Assist is an archive, not a hard delete. You will not see it on the list, and agents can no longer call its actions, but past instances remain in History. *** ## Best practices | Recommendation | Why it helps | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | One queue per kind of work | Billing exceptions and order lookups rarely belong on the same queue — put them on different actions. | | One action per job | `lookup_order` and `approve_refund` should be separate so the model picks the right one. | | Write the description for the model | “Call this when you cannot find the order with tools” beats “Order lookup.” | | Keep `assistReason` short and operational | Humans need “Refund \$42 on order 1832, customer received damaged item,” not a transcript dump. | | Turn **Blocking** on for work that cannot overlap | Approvals and lookups feel broken if the AI chats about something else while waiting. | | Turn **Cancelable** off for required steps | Identity checks and compliance confirmations should not be skippable. | | Test delay copy on a real call | Ten seconds of silence feels longer on the phone than in chat. | | Staff the queue before you enable the action | An Assist with nobody on the queue always hits queue timeout. | *** ## Example: order lookup A support agent can answer FAQs from the knowledge base, but order systems are behind a desktop the AI cannot reach. 1. Create an Assist named `Order desk`. 2. Add an action named `lookup_order`, pointed at the `Support` queue. 3. Description: `Ask a teammate to look up an order in the order system. Use this when the customer asks for status, tracking, or contents and no tool can retrieve it.` 4. Parameters schema with required `orderId`. 5. Start message: `Give me a moment — I’ll check that order with a colleague.` 6. Assign teammates to the `Support` queue and confirm they can see **Contact Center → Assists**. During a call, when the customer says “Where is order 1832?”, the model calls `lookup_order`. The caller stays with the AI. A teammate sees the request, looks up the order, and replies. The AI continues with the answer. *** ## Frequently asked questions Yes. Assists are workspace-scoped. Link the same Assist to every agent that should be able to request that kind of help. No. Actions are loaded when a conversation starts. New conversations pick up the latest configuration. Rejecting means the teammate cannot do the work (the caller hears the error line). Closing means the work is done and the AI should continue (the caller hears the human-agent close line). Tighten the description, mention the action in the agent prompt, and make sure the Assist is linked to that agent. Vague descriptions (“help with orders”) compete with tools and knowledge base. Confirm the queue has available teammates, they are looking at **Contact Center → Assists**, and the queue timeout is long enough for your staffing. Blocking actions feel slower to callers — consider shorter delay intervals with clearer copy rather than a longer timeout. Only if **Cancelable** is on. The model then has a cancel tool and the caller hears the user-cancel line. *** ## Related Connect APIs the agent can call on its own, without a human in the loop. Hand the live call to a person when the customer needs to speak to someone. Configure the voice agent that will call your Assist actions. A worked example of human-in-the-loop help during a live call. > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Dynamic Variables & Templating Source: https://docs.oration.ai/guides/agents/dynamic-variables Create personalized, context-aware agent prompts using dynamic variables, conditional logic, and data formatting ## Overview Oration enables dynamic content in agent prompts and conversations. Create personalized, context-aware interactions by injecting variables, applying filters, and using conditional logic directly in your agent prompts. Use double curly braces `{{ }}` for variables and `{% %}` for logic tags to create data-driven prompts that adapt to each conversation. ### Key Benefits * **Dynamic Personalization**: Insert customer names, account details, and contextual information * **Conditional Logic**: Show different content based on customer data or conversation state * **Data Formatting**: Apply filters to format dates, numbers, and text automatically * **Reusable Templates**: Create flexible prompts that work across different scenarios *** ## Using Dynamic Variables in Conversations ### Basic Variable Injection Inject dynamic variables into your agent prompts: ```liquid theme={null} Hello {{name}}, welcome to {{companyName}}! I see you're calling about your account {{account.id}}. How can I help you today? ``` ### Conditional Content Use conditional logic to personalize responses based on customer data: ```liquid theme={null} {% if customer.isPremium %} As a premium member, I can offer you priority support and exclusive options. {% else %} I'd be happy to help you today. Did you know we offer premium support for faster service? {% endif %} {% if customer.lastPurchaseDate %} I see your last purchase was on {{customer.lastPurchaseDate | date: "%B %d, %Y"}}. {% endif %} ``` ### Working with Nested Variables Oration supports complex nested data structures in variables. You can access nested properties using dot notation and work with arrays and objects seamlessly. ### Accessing Nested Properties ```liquid theme={null} {{customer.profile.firstName}} {{customer.address.street}} {{order.items.first.name}} {{customer.orders[0].total}} {{customer.phoneNumbers[1]}} ``` ### Working with Objects ```liquid theme={null} Customer: {{customer.profile.firstName}} {{customer.profile.lastName}} Email: {{customer.profile.contact.email}} Address: {{customer.profile.address.street}}, {{customer.profile.address.city}} Account Type: {{account.settings.type | capitalize}} Preferences: {{account.settings.preferences.notifications}} ``` ### Working with Arrays ```liquid theme={null} Your recent orders: {% for order in customer.orders %} - Order #{{order.id}}: {{order.total | currency}} on {{order.date | date: "%B %d, %Y"}} {% endfor %} Total orders: {{customer.orders.size}} Latest order: {{customer.orders.first.total | currency}} {% if customer.orders.size > 0 %} Most recent purchase was {{customer.orders.first.date | date: "%B %d"}}. {% endif %} {% assign productNames = products | map: "name" %} Available products: {{productNames | array_to_sentence_string}} {% assign customerInterests = customer.interests %} I see you're interested in {{customerInterests | array_to_sentence_string}}. {{customer.phoneNumbers | array_to_sentence_string: "or"}} {% if customer.preferences.size == 1 %} Your preference is {{customer.preferences.first}}. {% else %} Your preferences are {{customer.preferences | array_to_sentence_string}}. {% endif %} ``` ### Complex Nested Structures ```liquid theme={null} {{organization.departments.sales.manager.name}} {{user.preferences.notifications.email.frequency}} {% if customer.subscription.plan.features.premiumSupport %} You have access to our premium support team. Support hours: {{customer.subscription.plan.supportHours.start}} - {{customer.subscription.plan.supportHours.end}} {% endif %} {% for contact in customer.emergencyContacts %} Emergency Contact: {{contact.name}} ({{contact.relationship}}) Phone: {{contact.phone | default: "Not provided"}} {% endfor %} ``` ### Safe Navigation Use conditional checks to avoid errors when nested properties might not exist: ```liquid theme={null} {% if customer.profile %} Name: {{customer.profile.firstName | default: "Not provided"}} {% endif %} {% if customer.orders.size > 0 %} Last order: {{customer.orders.first.total | currency}} {% else %} No previous orders found. {% endif %} {{customer.profile.firstName | default: "Valued Customer"}} {{customer.address.city | default: "your area"}} ``` *** ## Default Variables Oration provides several built-in system variables that are always available in your prompts: ### System Variables | Variable | Description | Example | | ------------- | ----------------------------- | ---------------------------------------------- | | `language` | Current conversation language | `"en-US"` | | `currentTime` | Full current date and time | `"Monday, August 27, 2024 at 12:25:37 PM IST"` | | `currentDate` | Current date only | `"Monday, August 27, 2024"` | ### Usage Examples ```liquid theme={null} Today is {{currentDate}} and the current time is {{currentTime}}. {% if language == "en-US" %} I'll be speaking with you in English today. {% elsif language == "es-ES" %} Hablaré contigo en español hoy. {% endif %} ``` ### Custom Dynamic Variables Define custom variables that are evaluated at runtime: ```liquid theme={null} Welcome to {{company.name}}! Your account balance is {{customer.balance | currency}}. The weather today is {{weather.current | capitalize}}. ``` *** ## Data Formatting Filters Filters transform variable output using the pipe `|` operator. Most useful filters for agent prompts: ### Text Formatting ```liquid theme={null} {{customer.name | capitalize}} {{product.code | upcase}} {{customer.email | downcase}} {{customer.notes | strip}} {{description | truncate: 100}} {{phone | replace: "-", " "}} ``` ### Date and Time Formatting ```liquid theme={null} {{order.date | date: "%B %d, %Y"}} {{order.date | date: "%m/%d/%Y"}} {{order.date | date: "%A, %B %d"}} {{order.date | date: "%-d days ago"}} ``` ### Number Formatting ```liquid theme={null} {{price | currency}} {{price | currency: "EUR"}} {{rating | round: 1}} {{revenue | number_with_delimiter}} ``` ### Conditional and Logic Filters ```liquid theme={null} {{customer.name | default: "Valued Customer"}} {% unless customer.email == blank %} I'll send a confirmation to {{customer.email}}. {% endunless %} {% assign statusText = order.status | map: "pending" => "Processing", "shipped" => "On the way" %} ``` ### Advanced Filter Combinations ```liquid theme={null} {{customer.name | strip | capitalize | default: "Guest"}} Your account ({{account.id | upcase}}) has a balance of {{account.balance | currency}} as of {{account.lastUpdated | date: "%B %d at %I:%M %p"}}. {% assign urgency = ticket.priority | downcase %} This is a {% if urgency == "high" %}🔴 HIGH PRIORITY{% elsif urgency == "medium" %}🟡 MEDIUM PRIORITY{% else %}🟢 STANDARD{% endif %} request. ``` *** ## Essential Liquid JS Keywords & Syntax Understanding these key Liquid JS keywords will help you create more powerful and flexible agent prompts. These are the most commonly used control structures and operators. ### Control Flow Keywords #### Conditionals ```liquid theme={null} {% if customer.status == "premium" %} Premium customer benefits apply. {% elsif customer.status == "standard" %} Standard customer service available. {% else %} Basic support provided. {% endif %} {% unless customer.email == blank %} I'll send you a confirmation email at {{customer.email}}. {% endunless %} {% case customer.priority %} {% when "high" %} 🔴 High priority support {% when "medium" %} 🟡 Medium priority support {% when "low" %} 🟢 Standard support {% else %} Regular customer service {% endcase %} ``` #### Loops and Iteration ```liquid theme={null} {% for order in customer.orders %} Order {{forloop.index}}: {{order.total | currency}} {% endfor %} {% for item in cart.items %} {% if item.onSale %} 🏷️ SALE: {{item.name}} - {{item.price | currency}} {% endif %} {% endfor %} {% for order in customer.orders %} {{order.id}}: {{order.total | currency}} {% else %} No orders found. {% endfor %} ``` ### Variable Assignment and Manipulation ```liquid theme={null} {% assign fullName = customer.firstName | append: " " | append: customer.lastName %} {% assign discountRate = 0.15 %} {% assign isEligible = customer.years >= 2 %} {% capture greeting %} Hello {{customer.name}}, welcome to {{company.name}}! {% endcapture %} {% assign counter = 0 %} {% increment counter %} {% decrement counter %} ``` ### Comparison and Logic Operators ```liquid theme={null} {% if status == "active" %}Active account{% endif %} {% if status != "inactive" %}Account is working{% endif %} {% if customer.age >= 18 %}Adult customer{% endif %} {% if order.total < 100 %}Small order{% endif %} {% if balance > 0 %}Positive balance{% endif %} {% if items <= 5 %}Few items{% endif %} {% if customer.isPremium and customer.balance > 0 %} Premium customer with positive balance {% endif %} {% if customer.email == blank or customer.phone == blank %} Missing contact information {% endif %} {% if customer.interests contains "technology" %} Tech-savvy customer detected {% endif %} ``` ### Special Keywords and Properties ```liquid theme={null} {% for item in items %} {% if forloop.first %}First item: {% endif %} {% if forloop.last %}Last item: {% endif %} {{item.name}} ({{forloop.index}} of {{forloop.length}}) {% endfor %} {% if customer.orders.size > 5 %} Frequent customer with {{customer.orders.size}} orders {% endif %} {% if customer.notes != empty %} Notes: {{customer.notes}} {% endif %} {% if customer.email != blank %} Email on file: {{customer.email}} {% endif %} {{customer.orders.first.date}} {{customer.orders.last.total}} {{customer.phoneNumbers[0]}} ``` ### Flow Control Keywords ```liquid theme={null} {% for order in customer.orders %} {% if order.status == "cancelled" %} {% break %} {% endif %} Processing order {{order.id}} {% endfor %} {% for item in cart.items %} {% if item.outOfStock %} {% continue %} {% endif %} Available: {{item.name}} {% endfor %} ``` ### Comments and Documentation ```liquid theme={null} {%- comment -%} Multi-line comment This won't appear in output {%- endcomment -%} {%- if customer.name -%} Hello {{customer.name}}! {%- endif -%} ``` ### Advanced Keywords ```liquid theme={null} {% tablerow product in products cols:3 %} {{product.name}}: {{product.price | currency}} {% endtablerow %} {% raw %} {{customer.name}} will not be processed {% endraw %} {% render 'customer-info', customer: customer %} ``` ### Best Practices with Keywords ```liquid theme={null} {% assign customerGreeting = "Hello " | append: customer.name %} {% if customer.orders.size > 0 %} {% assign latestOrder = customer.orders.first %} {% if latestOrder.status == "delivered" %} Your recent order ({{latestOrder.id}}) was delivered {{latestOrder.deliveredDate | date: "%B %d"}}. {% endif %} {% else %} This appears to be your first order with us! {% endif %} {% case customer.subscription.type %} {% when "basic" %} Basic plan features available {% when "premium" %} Premium features unlocked {% when "enterprise" %} Full enterprise access {% endcase %} ``` *** ## Best Practices ### Always Provide Fallbacks ```liquid theme={null} Hello {{customer.name | default: "there"}}! Hello {{customer.name}}! ``` ### Use Meaningful Variable Names ```liquid theme={null} {{customer.preferredName | default: customer.firstName}} {{cust.pref | default: cust.fn}} ``` ### Format Data Consistently ```liquid theme={null} Account created: {{account.createdDate | date: "%B %d, %Y"}} Last login: {{account.lastLogin | date: "%B %d, %Y"}} Current balance: {{account.balance | currency}} Credit limit: {{account.creditLimit | currency}} ``` ### Keep Logic Simple ```liquid theme={null} {% if customer.isPremium %} You have premium support access. {% endif %} {% if customer.type == "premium" and customer.status == "active" and customer.balance > 0 %} {% endif %} ``` *** ## Common Use Cases ### Customer Service Agent ```liquid theme={null} Hello {{customer.firstName | default: "there"}}! I'm {{agent.name}}, your support specialist. {% if customer.supportHistory.size > 0 %} I can see we've helped you {{customer.supportHistory.size}} time{% if customer.supportHistory.size > 1 %}s{% endif %} before. Your last interaction was about {{customer.supportHistory.first.subject}}. {% endif %} What can I help you with today? ``` ### Sales Agent ```liquid theme={null} Hi {{lead.name}}! Thanks for your interest in {{product.name}}. {% if lead.budget %} I see you mentioned a budget of {{lead.budget | currency}}. {% endif %} {% if lead.company %} I'd love to learn more about how {{product.name}} could help {{lead.company}} {% if lead.industry %}in the {{lead.industry}} industry{% endif %}. {% endif %} What specific challenges are you looking to solve? ``` ### Appointment Scheduling ```liquid theme={null} {% assign nextSlot = availableSlots.first %} {% if nextSlot %} I have availability {{nextSlot.date | date: "%A, %B %d"}} at {{nextSlot.time | date: "%I:%M %p"}}. {% else %} I don't have any immediate availability, but I can check next week. {% endif %} {% if customer.timezone %} All times are in {{customer.timezone}} timezone. {% endif %} ``` *** ## Technical Reference Oration's dynamic templating is powered by **LiquidJS**, a robust templating engine that provides the syntax and filters described in this guide. For advanced use cases and additional filters not covered here, you can refer to the [LiquidJS documentation](https://liquidjs.com/) for complete technical details and extended functionality. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Knowledge Base Source: https://docs.oration.ai/guides/agents/knowledge-base How to create, manage, and use Knowledge Bases in Oration AI ## What is a Knowledge Base? A **Knowledge Base** in Oration AI is a centralized collection of documents, FAQs, product information, and other resources that your agents use to answer customer questions accurately and consistently. Think of it as your agent’s personal library—always available, always up-to-date. *** ## How Knowledge Bases Work When a customer asks a question, your agent searches the connected Knowledge Bases to find the most relevant information. This ensures that responses are always based on the latest and most accurate data you provide. You can create multiple Knowledge Bases for different teams, products, or use cases. Each Knowledge Base can contain one or more documents, and you can update them at any time. *** ## Creating and Managing Knowledge Bases Post Call Analysis 1. **Create a Knowledge Base:**\ In the Oration AI dashboard, go to the **Knowledge Bases** section and click **Create Knowledge Base**. Give it a descriptive name (e.g., “Sales”, “Product Catalogue”, “Company FAQs”). 2. **Add Documents:**\ Upload documents, paste text, or import content relevant to your business. Each document can be updated or replaced as your information changes. 3. **Organize and Manage:**\ Group related documents together, assign owners, and keep your Knowledge Base organized for easy access and maintenance. 4. **Connect to Agents:**\ Assign one or more Knowledge Bases to your agents. When a customer interacts with an agent, it will use the connected Knowledge Bases to answer questions.See video below. Post Call Analysis *** ## Best Practices * **Keep it current:** Regularly update your Knowledge Bases to ensure agents always provide accurate information. * **Be specific:** Use clear titles and organize documents by topic for faster search and retrieval. *** ## Example Use Cases * **Sales:** Equip your sales agents with up-to-date product specs, pricing, and objection handling. * **Support:** Provide troubleshooting guides and company policies for customer support agents. * **Internal FAQs:** Centralize answers to common employee or customer questions. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Agent Memory Source: https://docs.oration.ai/guides/agents/memories Let your agents remember customers across conversations — no more repeating themselves. ## What is Agent Memory? Agent Memory lets your agents remember key details about a customer across multiple conversations. Instead of starting fresh every time, your agent can recall what matters — preferences, past requests, important notes — and use that context to deliver a better experience. When memory is enabled, your agent automatically captures relevant information during a conversation and retrieves it the next time it speaks with the same customer. *** ## Enabling Memory Memory is configured per agent, in the **Advanced Settings** tab when creating or editing an agent. ### Steps to enable 1. Open your agent and go to **Advanced Settings** 2. Find the **Memory** section 3. Toggle **Memory Enabled** on 4. Set a **Retention Duration** — how long memories should be kept before they expire That's it. Once enabled, your agent will start capturing and using customer memories automatically. *** ## Retention Duration The retention duration controls how long a memory is kept before it's automatically deleted. * **Set a duration** (e.g. 30 days, 6 months, 1 year) — the memory expires after that period * **Leave it empty / set to indefinitely** — the memory is kept **forever** Use shorter durations for temporary context (a promotion, a one-time request) and longer durations or "forever" for persistent details like allergies, accessibility needs, or long-standing preferences. *** ## Viewing Customer Memories Once your agent starts capturing memories, you can view them from the **Customers** section. 1. Go to **Customers** in the navigation menu 2. Click on a customer to open their profile 3. Select the **Memories** tab The memories table shows: | Column | Description | | -------------- | ---------------------------------------------------------------- | | **Value** | The remembered detail about the customer | | **Agent Name** | Which agent captured this memory | | **Expires At** | When the memory will be removed — or **"–"** if it never expires | *** ## How Memory Works in Practice A customer calls your restaurant booking agent and mentions they're allergic to shellfish and prefer a quiet table. Your agent captures this. When they call back weeks later, the agent already knows — no need for the customer to repeat themselves. Once the retention period ends, the memory is automatically removed. If the customer calls after that, they'd mention it again. *** > Need help? Reach out to us at [support@oration.ai](mailto:support@oration.ai) # Prompting Guide Source: https://docs.oration.ai/guides/agents/prompting-guide Master the art of writing prompts that create exceptional AI agents ## Introduction Creating an effective AI agent starts with writing clear, purposeful prompts. This guide teaches you how to craft instructions that transform your Oration AI agents into knowledgeable, helpful assistants capable of delivering outstanding customer experiences. Whether you're building a customer service agent, appointment scheduler, or sales assistant, the techniques in this guide will help you create agents that understand context, maintain consistent personalities, and accomplish complex tasks with confidence. *** ## The Foundation: Understanding Prompt Impact Every word in your agent's prompt shapes how it behaves. Well-written prompts create agents that: * **Think before they speak**: Process customer requests thoughtfully and respond with relevant, helpful information * **Stay on brand**: Consistently reflect your company's voice, values, and communication style * **Handle complexity**: Navigate multi-step processes and unexpected situations with grace * **Build relationships**: Create positive customer experiences that feel natural and engaging Poorly constructed prompts result in agents that confuse customers, provide inconsistent service, or fail to complete important tasks. *** ## Building Effective Agent Instructions ### The Four-Layer Approach Structure your prompts using these essential layers: **Layer 1: Core Identity** Establish who your agent is and what role they play in your organization. **Layer 2: Communication Style** Define how your agent should speak, including tone, formality level, and personality traits. **Layer 3: Behavioral Rules** Set clear guidelines for how your agent should handle different types of situations. **Layer 4: Operational Procedures** Outline specific steps for completing tasks and achieving objectives. ### Practical Example Here's how this structure works in practice: ```md theme={null} [Core Identity] You are Jordan, a knowledgeable support specialist at Digital Solutions Inc. Your expertise covers account management, technical troubleshooting, and product guidance. [Communication Style] - Speak conversationally but maintain professionalism - Use encouraging language that builds customer confidence - Explain technical concepts in simple, relatable terms - Show genuine interest in solving customer problems [Behavioral Rules] - Always listen carefully to understand the full context before responding - Ask clarifying questions when information is incomplete - Acknowledge customer emotions and respond with appropriate empathy - Provide solutions step-by-step rather than overwhelming with information [Operational Procedures] 1. Begin each conversation by understanding the customer's primary goal 2. Gather all necessary information before proposing solutions 3. Test solutions with the customer to ensure they work 4. Confirm satisfaction before ending the conversation 5. Offer additional assistance and provide clear next steps ``` *** ## Crafting Natural Conversations ### Design for Real Dialogue Your agent should sound like a knowledgeable colleague, not a robotic script. Here's how to achieve natural communication: **Use Everyday Language** * Write "I'd be happy to help" instead of "I will assist you" * Choose "Let's figure this out together" over "I will resolve your issue" * Prefer "What's going on with your account?" to "Please describe your technical difficulty" **Include Human-Like Responses** ```md theme={null} [Natural Response Patterns] - Use acknowledgments: "I see what you mean," "That sounds frustrating" - Show understanding: "Let me make sure I've got this right..." - Express empathy: "I can understand why that would be confusing" - Use transitional phrases: "So here's what we can try," "Now that I know more about this..." ``` **Build in Flexibility** Allow your agent to adapt its responses based on customer needs rather than following rigid scripts. ### Managing Complex Interactions When designing multi-step processes, break them into manageable pieces: ```md theme={null} [Service Request Workflow] Step 1: Welcome and Discovery - Greet the customer warmly - Ask about their specific needs or concerns - Listen for emotional cues and respond appropriately Step 2: Information Gathering - Collect relevant details about their situation - Verify account information if needed - Clarify any confusing or incomplete information Step 3: Solution Development - Research available options using knowledge base - Present solutions in order of likelihood to help - Explain why you're recommending specific approaches Step 4: Implementation and Follow-up - Guide the customer through solution steps - Check that each step works before proceeding - Confirm the issue is fully resolved - Offer additional assistance or resources ``` *** ## Advanced Techniques for Professional Agents ### Contextual Awareness Teach your agent to recognize and respond to different types of customer situations: ```md theme={null} [Situation-Specific Responses] For frustrated customers: - Acknowledge their feelings first: "I can hear that this has been really frustrating" - Take ownership: "Let's get this sorted out for you right now" - Focus on solutions: "Here's exactly what we're going to do..." For confused customers: - Slow down and simplify: "Let me walk you through this step by step" - Check understanding frequently: "Does that make sense so far?" - Use analogies: "Think of it like..." to explain complex concepts For urgent requests: - Prioritize their needs: "I understand this is urgent—let's handle it immediately" - Set clear expectations: "I'll have an answer for you within the next five minutes" - Follow through consistently: Always deliver on commitments made ``` *** ## Troubleshooting Common Issues ### When Agents Miss the Mark **Problem: Responses Feel Scripted** * *Solution*: Add more personality traits and conversational elements * *Example*: Instead of "How may I assist you today?" try "What can I help you figure out?" **Problem: Inconsistent Quality** * *Solution*: Provide more specific examples of good vs. poor responses * *Example*: Include sample conversations showing desired interaction patterns **Problem: Information Overload** * *Solution*: Break complex information into smaller, digestible pieces * *Example*: "Let me start with the most important point, then we can dive into details" **Problem: Awkward Transitions** * *Solution*: Script natural bridges between conversation topics * *Example*: "Now that we've got that sorted, let's talk about..." *** Remember: Creating exceptional AI agents is both an art and a science. Start with clear objectives, test thoroughly, and never stop refining based on real customer interactions. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Tools Source: https://docs.oration.ai/guides/agents/tools How to extend your agent's capabilities with Tools in Oration AI ## What are Tools? Agents created using the Assistants API can be equipped with **tools** that allow them to perform more complex tasks or interact with your application. * Transfer calls or end calls * Access external data or APIs * Trigger workflows in your business systems * Send SMS messages, update records, and more *** ## Setting Up a Custom Tool You can create a custom tool action directly from the Oration AI dashboard. Here’s how to use the **Create Action** form: Post Call Analysis ### Field Explanations * **Name**\ The name of your tool action. Choose something descriptive (e.g., "Get Weather", "Update CRM Contact"). * **Method**\ Select the HTTP method for your API call. Options: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS`, `HEAD`. * **Description**\ Briefly describe what this tool does. This helps you and your team understand its purpose. * **Url Template**\ The endpoint your tool will call. You can use variables if needed (e.g., `https://api.example.com/users/{{userId}}`). * **Body Template**\ (Optional) The request body to send with your API call. Use this for `POST`, `PUT`, or `PATCH` methods. * **Speech During Execution**\ (Optional) What the agent should say while the tool is running (e.g., "Let me check that for you..."). * **Speech After Execution**\ (Optional) What the agent should say after the tool finishes (e.g., "I've updated your information."). * **Is Async**\ Enable this if you want the function to run in the background, such as uploading results silently. * **Schema**\ Provide a valid OpenAI-compatible JSON schema describing the parameters your tool expects. *** ## Example Use Cases * **Updating CRM records** during a call * **Sending follow-up SMS** after a conversation * **Fetching product information** from your database *** ## Best Practices * Use clear, descriptive names and descriptions for each tool. * Test your API endpoints before connecting them to your agent. * Use the speech fields to keep users informed during longer operations. * Keep your JSON schema up to date for accurate parameter validation. *** ## Related When the agent needs a **person** rather than an API, use [Assists](/guides/agents/assists) instead of a tool. Assists keep the AI on the line while a teammate handles the request from a contact-center queue. > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Voice Formatting Source: https://docs.oration.ai/guides/agents/voice-formatting Format agent output for natural-sounding speech in Oration AI ## Overview Voice formatting automatically transforms raw text from your language model into a format that sounds natural when spoken by text-to-speech technology. This feature helps your agents communicate more effectively by converting technical text into conversational speech patterns. Voice formatting enables your agents to naturally speak: * Numbers and currency (e.g., `$42.50` → "forty two dollars and fifty cents") * Phone numbers (e.g., `+1234567890` → "plus one two three four five six seven eight nine zero") * Dates, times, and percentages in conversational format. (Currenly this is limited to dates in the format `dd/mm/yyyy` or `dd-mm-yyyy` or `yyyy-mm-dd` or `yyyy/mm/dd`) (e.g., `10/05/2023` → "May 10th, 2023") By default, voice formatting is **disabled** for new agents. You can enable it in the agent settings to improve the naturalness of your agent's speech. These work for all languages supported by Oration AI. *** ## How Voice Formatting Works When enabled, voice formatting processes your agent's text output through a series of transformations. Each transformation targets specific patterns to make speech sound more natural and conversational. ### Formatting Transformations The formatting system applies these transformations in order: | **Step** | **Function** | **Description** | **Before** | **After** | | -------- | ------------------------- | --------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------ | | 1 | Format currency | Converts dollar amounts to spoken words | \$42.50 | forty two dollars and fifty cents | | 2 | Format emails | Replaces `@` with "at" and `.` with "dot" | [john@example.com](mailto:john@example.com) | john at example dot com | | 3 | Format dates | Converts dates into spoken format | 10-05-2023 | May tenth, two thousand twenty three | | 4 | Format times | Time expressions | 2:00 PM | two PM | | 5 | Format distances | Converts distance measurements | 5km | 5 kilometers | | 6 | Format units | Converts measurement units | 100g | 100 grams | | 7 | Format percentages | Converts percentage symbols | 50% | 50 percent | | 8 | Format phone numbers | Spaces out digits for clarity | +1234567890 | plus one two three four five six seven eight nine zero | | 9 | Remove markdown | Removes markdown symbols like `_`, `` ` ``, and `~` | `**Bold** and *italic*` | Bold and italic | | 10 | Format new lines | Converts line breaks to periods for smoother speech | Hello world`\n`to say | Hello world . to say | | 11 | Format colons | Replaces `:` with `.` for better phrasing | price: \$42.50 | price. forty two dollars and fifty cents | | 12 | Handle special characters | Speaks special characters like `/` and `_` | 5/207 | five slash two hundred and seven | | 13 | Format numbers | Handles general numbers appropriately | -9, 2.5, 2023 | minus nine, two point five, two thousand twenty three | *** ## Enabling Voice Formatting Voice formatting is controlled through your agent settings: ### In Agent Settings 1. Navigate to your **Agent Settings** 2. Go to the **Advanced Settings** tab 3. Find the **Voice Formatting** toggle 4. Enable the feature to activate natural speech formatting When enabled, all text output from your agent will be processed through the formatting system before being converted to speech. *** ## When to Use Voice Formatting **Enable voice formatting when:** * Your agent handles customer service calls * You need natural-sounding currency and number pronunciation * Your agent reads addresses, phone numbers, or dates * Professional, conversational tone is important **Consider keeping it disabled when:** * Your agent primarily handles technical support requiring precise terminology * You need exact control over pronunciation * Your use case involves specialized vocabulary that formatting might alter *** ## Best Practices ### Content Writing * Write naturally in your prompts—let formatting handle the technical conversion * Use standard formats for dates, currency, and numbers. * Dates should be in the format `dd/mm/yyyy` or `dd-mm-yyyy` or `yyyy-mm-dd` or `yyyy/mm/dd` * Currency should be in the format `$100` or `100 USD` * Numbers should be in the format `100` or `100.00` * Phone numbers should be in the format `+1234567890` * Percentages should be in the format `50%` * Distances should be in the format `5km` * Units should be in the format `100g` * Emails should be in the format `john@example.com` * Test your agent's speech output after enabling formatting * Do not mention any specific formatting for numbers, dates, currency, phone numbers, percentages, distances, units, emails, etc. in your agent's prompts as it may clash with the voice formatting system. * In case some numbers are not being formatted correctly, you can use `--` to separate the numbers into groups of digits you want to be formatted. For example: Pin code is `123456` can be written as `1--2--3--4--5--6` to make the Agent speak the numbers slowly. ### Testing * Enable voice formatting in a test environment first * Listen to how your agent pronounces different types of content * Adjust your content strategy based on formatting results *** ## Summary Voice formatting transforms your agent's text output into natural-sounding speech, making conversations more engaging and professional. While disabled by default, enabling this feature significantly improves the user experience for most voice applications. The formatting system handles common patterns automatically, requiring no changes to your agent's prompts or knowledge base content. Simply enable the feature in your agent settings to start delivering more natural voice interactions. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Reports & Insights Source: https://docs.oration.ai/guides/analytics/reports-and-insights Create data-driven reports and track key metrics with customizable insights for your AI conversations ## Overview Reports and Insights in Oration AI provide a powerful analytics framework for tracking, measuring, and understanding your AI conversation performance. Build comprehensive reports from pre-built templates or from scratch, customize visual insights with various chart types, and share findings with your team to make data-driven decisions. Jump-start your analytics with professionally designed report templates for common use cases Create tailored visualizations to track the metrics that matter most to your business Access up-to-date metrics and trends as your AI agents interact with customers Share reports and insights across your workspace for aligned decision-making ## Understanding Reports vs Insights ### Reports Reports are organized collections of insights that tell a complete story about your AI performance. Think of reports as dashboards that bring together multiple data visualizations and metrics into a cohesive view. **Key characteristics:** * Container for multiple insights * Can be created from templates or blank * Shareable with team members * Can be favorited for quick access * Include metadata like creator, description, and creation date ### Insights Insights are individual data visualizations that track specific metrics. Each insight focuses on a single measurement or trend, visualized through charts, graphs, or tables. **Key characteristics:** * Individual metric or KPI visualization * Customizable chart types (line, bar, area, pie, etc.) * Configurable time granularity (hourly, daily, weekly, monthly) * Can be added to multiple reports * Real-time data updates ## Quick start ### Create your first report 1. Navigate to **Reports** from the side navigation 2. Click **New Report** in the top-right corner 3. Select a template or choose **Blank Report** for custom creation 4. Configure report details (name, description) 5. Add insights to populate your report 6. Save and share with your team ### Create your first insight 1. Navigate to **Reports** and switch to the **Insights** tab 2. Click **New Insight** 3. Select the metric you want to track 4. Choose your visualization type 5. Configure time range and granularity 6. Name your insight and save ## Report templates Oration AI provides professionally designed templates to help you get started quickly. Each template is optimized for specific use cases and includes pre-configured insights. ### Available templates | Template | Description | Best for | | ----------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | | **Campaigns Performance** | Track campaign metrics, engagement rates, and ROI | Marketing teams measuring campaign effectiveness | | **Conversations Performance** | Monitor conversation volume, duration, and outcomes | Operations teams optimizing conversation quality | | **Agents Performance** | Evaluate individual agent metrics and efficiency | Team leads managing multiple AI agents | | **Customer Analytics** | Analyze customer behavior, satisfaction, and trends | Customer success teams understanding user patterns | | **Revenue Reports** | Track revenue metrics, conversions, and growth | Finance and sales teams monitoring financial performance | | **User Engagement** | Monitor active users, session duration, and retention | Product teams improving user experience | | **Support Tickets** | Manage support volume, resolution time, and satisfaction | Support teams optimizing response workflows | | **Product Performance** | Evaluate feature usage and product adoption | Product managers tracking feature success | | **Custom Dashboard** | Build personalized views with selected insights | Teams with specific reporting needs | ### Using templates When creating a new report, selecting a template automatically: * Configures relevant insights for that use case * Sets appropriate time ranges and granularity * Applies industry-standard visualization types * Includes recommended metrics and KPIs You can customize any template after creation by adding, removing, or modifying insights. ## Creating insights Insights are the building blocks of your reports. Each insight tracks a specific metric and presents it visually. ### Insight configuration options | Option | Description | Values | | ---------------------- | -------------------------------- | ----------------------------------------------- | | **Name** | Descriptive name for the insight | Text string (e.g., "Daily Conversation Count") | | **Metric** | The data point being measured | Conversations, Agents, Campaigns, Revenue, etc. | | **Visualization Type** | Chart style for presenting data | Line, Bar, Area, Pie, Donut, Table | | **Time Grain** | Data aggregation interval | Hourly, Daily, Weekly, Monthly | | **Date Range** | Period for data analysis | Last 7 days, Last 30 days, Custom range | | **Filters** | Criteria to narrow results | Agent ID, Campaign ID, Customer segment, etc. | ### Visualization types Choose the visualization that best represents your data: #### Line charts **Best for:** Tracking trends over time, identifying patterns, showing continuous data **Example use cases:** * Daily conversation volume * Weekly revenue trends * Monthly user growth #### Bar charts **Best for:** Comparing discrete categories, showing rankings, displaying counts **Example use cases:** * Agent performance comparison * Campaign engagement by channel * Support ticket categories #### Area charts **Best for:** Showing cumulative totals, visualizing part-to-whole relationships over time **Example use cases:** * Cumulative revenue * Stacked conversation outcomes * Multi-agent volume distribution #### Pie & Donut charts **Best for:** Showing proportions, displaying percentage breakdowns **Example use cases:** * Conversation outcome distribution * Customer segment breakdown * Agent workload distribution #### Tables **Best for:** Detailed data inspection, precise values, sortable metrics **Example use cases:** * Top performing agents list * Detailed campaign metrics * Customer engagement scores ### Time granularity Select the appropriate time grain based on your analysis needs: * **Hourly:** For real-time monitoring and intraday patterns * **Daily:** For day-to-day trends and week-over-week comparisons * **Weekly:** For monthly trends and reducing daily noise * **Monthly:** For long-term trends and year-over-year analysis Match your time grain to your data volume. Hourly granularity works well for high-volume operations, while monthly views are better for strategic planning. ## Building effective reports ### Report organization best practices **1. Start with context** Begin your report with high-level overview insights that set the stage. Include total volumes, success rates, and key trends. **2. Follow the data flow** Organize insights logically, moving from general metrics to specific details. For example: * Overall conversation volume → Conversation outcomes → Individual agent performance **3. Highlight anomalies** Include insights that help identify unusual patterns or outliers requiring attention. **4. End with actionable items** Conclude reports with insights that inform specific decisions or next steps. ### Example: Campaign Performance Report structure ``` 1. Campaign Overview Insights - Total conversations initiated - Overall engagement rate - Campaign ROI 2. Engagement Metrics - Conversation completion rate - Average conversation duration - Time-of-day engagement patterns 3. Outcome Analysis - Conversion rates by campaign - Drop-off points analysis - Customer feedback scores 4. Agent Performance - Individual agent metrics - Response time distribution - Quality scores 5. Recommendations - Top performing campaigns - Optimization opportunities - Resource allocation insights ``` ## Managing reports ### Favorite reports Mark frequently accessed reports as favorites for quick access: 1. Navigate to your report 2. Click the star icon in the report header 3. Access favorited reports from the **Favorite Reports** section Favorite reports appear at the top of your reports list and in your dashboard for convenient monitoring. ### Sharing reports Reports can be shared with workspace members: 1. Open the report you want to share 2. Click the **Share** button 3. Select team members or set workspace-wide access 4. Notify recipients via email (optional) Shared reports maintain real-time data, ensuring everyone sees current metrics. ### Report permissions | Permission Level | Can View | Can Edit | Can Delete | Can Share | | ---------------- | -------- | -------- | ---------- | --------- | | **Owner** | ✓ | ✓ | ✓ | ✓ | | **Editor** | ✓ | ✓ | ✗ | ✓ | | **Viewer** | ✓ | ✗ | ✗ | ✗ | ### Duplicating reports Create variations of existing reports: 1. Open the source report 2. Click the **More options** menu (three dots) 3. Select **Duplicate** 4. Modify the duplicate as needed This is useful for creating similar reports for different time periods, teams, or agents. ## Advanced features ### Combining insights from multiple sources Build comprehensive reports by combining insights from different data sources: * **Conversation data:** Volume, duration, outcomes * **Agent performance:** Response times, quality scores * **Campaign metrics:** Engagement, conversion rates * **Customer data:** Satisfaction scores, retention rates * **Revenue data:** Conversion value, lifetime value ### Custom time ranges While preset ranges (Last 7 days, Last 30 days) work for most cases, custom ranges enable: * **Specific campaign period analysis** * **Quarter-over-quarter comparisons** * **Event-driven reporting** (product launch, seasonal campaigns) * **Historical baseline establishment** To set a custom range: 1. Click the date selector in your insight configuration 2. Choose **Custom Range** 3. Select start and end dates 4. Apply to insight ### Filtering insights Apply filters to focus insights on specific segments: **Agent filters:** ``` agent_id = "asst_abc123" agent_name contains "Support" ``` **Campaign filters:** ``` campaign_id = "camp_xyz789" campaign_status = "active" ``` **Customer filters:** ``` customer_segment = "enterprise" customer_region = "North America" ``` **Outcome filters:** ``` conversation_outcome = "successful" call_duration > 300 (seconds) ``` ## Best practices ### Performance optimization **For faster report loading:** * Limit insights per report to 10-15 for optimal performance * Use appropriate time grains (avoid hourly for long date ranges) * Apply filters to reduce data volume * Cache frequently accessed reports by favoriting ### Data accuracy **Ensure reliable insights:** * Allow 5-10 minutes for real-time data processing * Verify date ranges match your analysis period * Cross-reference totals with raw conversation data * Document any filters applied to insights ### Meaningful metrics **Choose metrics that drive action:** * Focus on leading indicators, not just lagging metrics * Balance quantitative (numbers) with qualitative (satisfaction) data * Align metrics with business objectives * Review and update metrics quarterly ## Common use cases ### Executive dashboard Create a high-level overview for leadership: **Insights to include:** * Total conversation volume (trend line) * Overall success rate (big number + comparison) * Revenue generated (bar chart by period) * Customer satisfaction score (gauge chart) * Top 5 performing agents (table) **Time grain:** Daily or Weekly\ **Date range:** Last 30 days with previous period comparison ### Agent performance review Track individual agent effectiveness: **Insights to include:** * Conversations handled per agent (bar chart) * Average response time by agent (table) * Conversation outcomes by agent (stacked bar) * Customer feedback scores (line chart) * Peak performance hours (heatmap) **Time grain:** Daily\ **Date range:** Last 7 days ### Campaign ROI analysis Measure campaign effectiveness: **Insights to include:** * Campaign reach and engagement (funnel chart) * Conversion rates by campaign (bar chart) * Cost per conversation (table) * Revenue per campaign (pie chart) * Time-to-conversion (line chart) **Time grain:** Daily\ **Date range:** Campaign duration ## Troubleshooting ### Insight not showing data **Possible causes and solutions:** 1. **Insufficient data in selected range** * Solution: Expand date range or check if agent has processed conversations 2. **Filters too restrictive** * Solution: Review and relax filter criteria 3. **Data processing delay** * Solution: Wait 5-10 minutes for real-time data to populate 4. **Metric not applicable to selected agents** * Solution: Verify agents support the metric being tracked ### Report performance issues **If reports load slowly:** 1. Reduce number of insights (keep under 15) 2. Shorten date ranges for detailed time grains 3. Apply filters to limit data volume 4. Break large reports into focused sub-reports ### Data discrepancies **If numbers don't match expectations:** 1. Verify time zones match your workspace settings 2. Check for duplicate insights with different filters 3. Confirm date ranges align correctly 4. Review data processing timestamps ## Keyboard shortcuts Speed up your workflow with keyboard shortcuts: | Action | Shortcut | | ------------------ | ---------------------- | | Create new report | `Cmd/Ctrl + N` | | Create new insight | `Cmd/Ctrl + I` | | Search reports | `Cmd/Ctrl + K` | | Toggle favorites | `Cmd/Ctrl + D` | | Share report | `Cmd/Ctrl + Shift + S` | | Refresh data | `Cmd/Ctrl + R` | ## API access Programmatically access report data via the Oration API: ```javascript theme={null} // Fetch report data const response = await fetch('https://api.oration.ai/v1/reports/{reportId}', { headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const reportData = await response.json(); ``` See the [API Reference](/api-reference/reports) for complete documentation. Reports reflect data from conversations processed by your AI agents. Ensure agents are properly configured and active to collect meaningful metrics. Schedule regular report reviews with your team to identify trends, celebrate wins, and address areas for improvement. Data-driven decisions lead to better AI performance. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Coaching Source: https://docs.oration.ai/guides/brand-voice/coachings Standardize how agents respond to common or critical situations. ## Overview **Coaching** in Oration is a powerful way to train your agents to handle specific scenarios with the right responses. By defining coaching instructions, you ensure that your agents consistently follow best practices and company guidelines during customer interactions. *** Coaching Overview ## Viewing and Managing Coachings The **Coaching** dashboard provides an overview of all coaching instructions you’ve created. For each coaching, you can see: * **Scenario:** The situation or trigger for the coaching (e.g., "Where the customer is inquiring about the pricing plan"). * **Assigned Agents:** Which agents will receive this coaching. * **Status Toggle:** Enable or disable coaching as needed. You can easily add, edit, or remove coaching instructions to keep your training up to date. *** ## Creating a New Coaching To add a new coaching instruction, click the **Create Coaching** button. Coachings Alternatively, you can quickly create a new coaching directly from a conversation transcript in the history view. Just click the **Coaching** icon next to the relevant section of the transcript to launch the coaching creation form with context pre-filled. Coachings ### Field Explanations * **Scenario**\ Describe the situation when this coaching should be triggered.\ *Example: "When the customer says they want a discount"* * **Agent Behavior**\ Provide a guideline or example of how the agent should respond.\ *Example: "Inform the customer that the prices are not negotiable"* * **Apply for all agents**\ Check this box if you want the coaching to apply to every agent in your organization. * **Agents**\ Select specific agents who should receive this coaching if not applying to all. Click **Save** to activate the coaching. The selected agents will now follow this guidance whenever the defined scenario occurs. *** ## Example Scenarios * **Scenario:** When the customer asks about payment status\ **Agent Behavior:** Politely check if the customer has paid 10 percent of the total amount. * **Scenario:** Where the customer is inquiring about the pricing plan\ **Agent Behavior:** Clearly explain the available pricing options. *** ## Best Practices * Use clear, specific scenarios to trigger coaching at the right moments. * Write actionable, concise agent behaviors for easy adoption. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Terms Source: https://docs.oration.ai/guides/brand-voice/terms Manage and enforce your company’s terminology for consistent communication in Oration AI ## What are terms? The **Terms** section in Oration AI lets you manage, enforce, and share your company’s unique terminology. By defining approved terms and their replacements, you ensure consistency and clarity across all customer and agent communications. **Why is this important?** * **Brand Consistency:** Ensure your agents always use the correct product names, service terms, or industry language. * **Compliance:** Enforce the use of approved language for regulatory or legal reasons. * **Clarity:** Avoid confusion by standardizing how information is presented to customers. *** ## Creating a New Term To add a new term, click the **New Term** button. You’ll see a form like this: Terms ### Field Explanations * **Term**\ The word or phrase you want to manage (e.g., "CRM", "client"). * **Replacement**\ The approved alternative for the term (e.g., "Customer Relationship Management", "customer"). * **Description**\ Provide context, usage examples, or detailed instructions for when and how to use the term or its replacement. * **Strict Replace**\ When enabled, the system will replace the term with its approved alternative in all communications. When disabled, the term can be used in conversations, but the system won't enforce mandatory replacement. ### Example Suppose your company has rebranded a product from "Oration Suite" to "Oration Platform". You want to ensure all agents use the new name. * **Term:** Oration Suite * **Replacement:** Oration Platform * **Description:** "Oration Suite" is the old product name. Always refer to it as "Oration Platform" in all customer communications. * **Strict Replace:** Enabled Or, to standardize industry language: * **Term:** client * **Replacement:** customer * **Description:** Use "customer" instead of "client" for consistency across all support and sales interactions. * **Strict Replace:** Enabled Click **Create** to save your term. It will now be enforced across your agents and communications. *** ## Best Practices * Enable strict replace for terms that must always be substituted. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Managing Campaigns Source: https://docs.oration.ai/guides/campaigns/managing-campaigns A guide to creating and managing outbound campaigns in Oration AI ## Campaigns in Oration Campaigns in Oration AI enable you to reach your customers with AI-powered calls at scale. Set up automated outbound campaigns to engage customers, conduct surveys, deliver important messages, or follow up on services. With intelligent scheduling, SQL-based targeting, and comprehensive attempt management, campaigns help you connect with the right customers at the right time. Step by step, learn how to create and configure your first campaign. Select **Campaigns** from the side navigation and click **New Campaign** button on the right top corner. *** ### Using Customer Uploaded Data in Campaigns To enhance your campaign targeting, you can upload customer data in CSV format. This allows you to leverage existing customer information for more effective outreach. Here’s how to do it: 1. **Prepare Your CSV File**: Create a CSV file with the necessary fields that match your SQL query requirements. Below is a sample snippet of the CSV format you should use: ### File Structure ```csv theme={null} phoneNumber,campaign,identifier,customerName,customerType,lastPurchaseDate +919876543210,welcome-series-q1,CUST-12345,John Smith,welcome-campaign,2024-01-15 +15551234567,welcome-series-q1,CUST-67890,Jane Doe,welcome-campaign,2024-02-20 +447700900123,welcome-series-q1,CUST-11111,Bob Johnson,welcome-campaign,2024-01-30 ``` * **identifier**: Unique identifier for each customer. * **customerType**: Type of customer (e.g., 'welcome-campaign'). * **lastPurchaseDate**: The date of the customer's last interaction or purchase. This is customized variable aka **Dynamic Variable** used for personalized message for each customer. 2. **Upload the CSV File**: Navigate to the **Customers** section in the platform and upload your prepared CSV file. Ensure that the data is correctly formatted and all required fields are included. 3. **Create your campaign**: Once the customer data is uploaded, you are all set to create your campaign. *** ## Create New Campaign Create New Campaign The **Create New Campaign** form is where you define all aspects of your outbound campaign. ### Campaign Status **Is Enabled:** Toggle to activate or deactivate your campaign. When enabled, the campaign will run according to its schedule and settings. ### Agent Selection **Agent:** Select the AI agent that will handle the calls for this campaign. Choose from your existing agents that are configured with appropriate prompts and behaviors for your campaign goals. ### Campaign Identity **Name:** Enter a descriptive name for your campaign (e.g., "Welcome Series Q1 2024"). This helps you identify and manage multiple campaigns. ### Customer Targeting **SQL queries to fetch target customers for this campaign first attempt:** Write SQL queries to identify which customers should receive calls in the initial attempt. This allows precise targeting based on customer data, demographics, purchase history, or any other criteria in your database. For example: ```sql theme={null} SELECT cust.id FROM public.customers cust WHERE cust.metadata->>'customerType' = 'campaign' AND cust.workspace_id = {{WORKSPACE_ID}} AND cust.updated_at BETWEEN {{CAMPAIGN_RUN_START_DATE}} AND {{CAMPAIGN_RUN_START_DATE}} + INTERVAL '1 day'; ``` ### What does this query do? This query looks into the customers list and picks out the IDs of only those customers who match certain conditions. ### Step‑by‑step explanation: 1. **Filter by customer type**\ Every customer has some extra information stored in a metadata field. One of these details is `customerType`. In this query, we are looking only for customers where `customerType = 'campaign'`. You can change 'campaign' to any other value depending on the type of customers you want to filter — for example, 'lead', 'prospect', or 'subscriber'. 2. **Filter by workspace**\ Each customer belongs to a specific workspace. The query uses `WORKSPACE_ID` to fetch customers for only that specific workspace. This is managed internally by the Oration team, so you usually don’t need to change it. 3. **Filter by date range**\ It only picks customers whose `updated_at` date is after the campaign run start date (`CAMPAIGN_RUN_START_DATE`) and before one day after that date. In simple terms, it’s finding customers who were updated within 24 hours from the start of the campaign. ### In short: "Give me the IDs of all customers from this workspace, whose type is ‘campaign’, and who were updated within one day after the campaign started." #### Reattempt Rule Sql Queries **SQL queries to fetch target customers for this campaign for reattempts:** Define separate SQL queries for customers who should receive follow-up attempts. This enables different targeting logic for reattempts, such as excluding customers who have already responded or focusing on high-priority segments. ```sql theme={null} WITH customer_speech_status as ( SELECT c.customer_id, BOOL_OR(t.messages is not null and t.messages ilike '%userMessage%') as has_spoken FROM conversations c LEFT JOIN transcripts t on c.id = t.conversation_id WHERE c.conversation_type = 'telephony' and c.campaign_run_id = {{CAMPAIGN_RUN_ID}} and c.workspace_id = {{WORKSPACE_ID}} and c.customer_id is not null GROUP BY c.customer_id ) SELECT cust.id FROM customers cust INNER JOIN ( select customer_id from customer_speech_status where has_spoken = false or has_spoken is null ) unpicked on cust.id = unpicked.customer_id WHERE ( cust.metadata->>'customerType' = 'welcome-campaign' and cust.workspace_id = {{WORKSPACE_ID}} and cust.updated_at > {{CAMPAIGN_RUN_START_DATE}} and cust.updated_at < {{CAMPAIGN_RUN_START_DATE}} + interval '1 day' ); ``` ### What does this query do? This query finds the IDs of customers who: * Belong to a specific campaign and workspace * Were updated within one day of the campaign starting * Had a telephony call conversation during that campaign but no actual user messages recorded in the transcript. ### Step‑by‑step explanation 1. **Identify customers from telephony conversations without user messages**\ First, the query looks at the conversations table and picks out conversations that: * Are of type telephony (phone calls) * Are part of a specific campaign run (CAMPAIGN\_RUN\_ID) * Belong to a specific workspace (WORKSPACE\_ID) * Have a linked customer (customer\_id is not empty) * Either have no conversation transcript (t.messages IS NULL) or the transcript text does not contain the term userMessage (meaning the agent spoke, but the system did not detect anything from the customer). This produces a list of customer IDs who took part in such calls. 2. **Match those customers in the customers list**\ The query then joins this list with the customers table to get details for those customers. 3. **Apply customer filters**\ The results are further filtered to include only customers who: * Have customerType in their metadata set to 'welcome-campaign'. This is just a tag to identify the campaign type — the name can be different depending on the campaign. * Belong to the same workspace indicated by WORKSPACE\_ID * Were updated after the campaign started (CAMPAIGN\_RUN\_START\_DATE) and before one day later. In other words, they were updated during the first 24 hours of the campaign. ### In short: "Give me the IDs of all customers from this workspace, tagged for the ‘campaign’, updated within 24 hours of the campaign start, who had a telephony conversation during this campaign but no actual voice/message recorded from the customer." *** ## Call Attempt Create New Campaign ### Campaign Type **Type of campaign:** Select the campaign type from available options. Choose "single" for one-time campaigns or "recurring" for campaigns that run on a regular schedule based on your campaign strategy. ### Attempt Management * **Max Attempts Daily:** Set the maximum number of call attempts per customer per day. This prevents overwhelming customers while ensuring adequate outreach. * **Max Re Attempt Days:** Define the maximum number of days over which reattempts should be made. This controls the campaign duration and prevents indefinite calling. * **Min Re Attempt Delay:** Set the minimum delay between reattempts to the same customer. This ensures appropriate spacing between calls. ### Concurrency Control **Max Concurrency:** Specify the maximum number of simultaneous calls your campaign can make. This helps manage system resources and calling capacity. *** ## Concurrency and Scheduling Create New Campaign ### Scheduling **Schedule:** Configure when your campaign should run. Set up recurring schedules or specific time windows for optimal customer engagement. ### Business Hours **Business Hours:** Define the hours during which calls can be made. Click "Click to set business hours" to configure appropriate calling windows that respect customer preferences and regulations. ### Campaign Timeline * **Start Date:** Set the earliest time to make calls using 24-hour format (dd/mm/yyyy, --:-- --). This defines when your campaign becomes active. * **End Date:** Set the latest time to make calls using 24-hour format (dd/mm/yyyy, --:-- --). This automatically stops the campaign after the specified date. *** ## Best Practices ### SQL Query Tips * Use precise targeting criteria to reach the most relevant customers * Test your SQL queries with small datasets before launching full campaigns * Consider customer preferences and opt-out status in your queries * Use different logic for first attempts vs. reattempts ### Scheduling Recommendations * Set business hours that align with your customers' time zones * Avoid calling during holidays or inappropriate hours * Use reasonable attempt delays to prevent customer annoyance * Monitor campaign performance and adjust timing as needed ### Campaign Management * Start with small test campaigns before scaling up * Monitor max concurrency to ensure system performance * Set appropriate end dates to prevent campaigns from running indefinitely * Regularly review and update your targeting criteria *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Uploading Customers Source: https://docs.oration.ai/guides/campaigns/uploading-customers A guide to uploading customer data via CSV for campaigns in Oration AI ## Uploading Customers for Campaigns Upload your customer data via CSV to populate campaigns with targeted customer lists. Step by step, learn how to upload and map customer data. Select **Customers** from the side navigation, choose your campaign, and click **Upload Customers** to begin. *** ## CSV Upload Process Upload Customers ### Upload CSV File **Drag and drop** your CSV file or click **Browse** to select a file from your computer. The platform supports standard CSV formats with comma-separated values. *** ## CSV Field Requirements Your CSV file must include the following mandatory fields and can optionally include dynamic variables for personalized messaging. #### Phone Number **phoneNumber** - The customer's phone number including ISD code * **Format:** Must include country code prefix (e.g., `+91` for India, `+1` for US) * **Example:** `+919876543210`, `+15551234567` * **Required:** Yes * **Usage:** Used as the primary contact method for AI-powered calls #### Campaign Identifier **campaign** - The campaign identifier * **Purpose:** Links each customer to a specific campaign * **Required:** Yes * **Example:** `welcome-series-q1`, `survey-2024-customer-satisfaction` #### Customer Identifier **identifier** - Unique identifier for each customer * **Purpose:** Ensures each customer is uniquely tracked in the system * **Required:** Yes * **Options:** * Use phone number as identifier * Use internal customer ID from your CRM * Use any unique customer reference * **Example:** `CUST-12345`, `+919876543210`, `user_67890` ### Optional Dynamic Variables Include any additional fields that your agent's prompt uses for personalized messaging, preferably in camel case. These fields are automatically available as variables in your agent prompts. #### Common Dynamic Variables **customerName** - Customer's name for personalized greetings * **Example:** `"John Smith"`, `"Priya Patel"` * **Usage:** `Hello {{customerName}}, this is...` **accountType** - Customer's account or subscription level * **Example:** `"Premium"`, `"Basic"`, `"Enterprise"` * **Usage:** `As a {{accountType}} customer, you have access to...` **lastPurchaseDate** - Date of last interaction or purchase * **Example:** `"2024-01-15"` * **Usage:** `We noticed your last purchase was on {{lastPurchaseDate}}...` **customField1, customField2, etc.** - Any other relevant customer data * **Examples:** `"renewal_date"`, `"subscription_status"`, `"preferred_language"` * **Usage:** Available as `{{renewal_date}}`, `{{subscription_status}}`, etc. *** ## Field Mapping Interface Field Mapping After uploading your CSV, Oration AI automatically detects column headers and suggests field mappings. Review and adjust these mappings to ensure data is correctly assigned. *** ## CSV Format Guidelines ### File Structure ```csv theme={null} phoneNumber,campaign,identifier,customerName,customerType,lastPurchaseDate +919876543210,welcome-series-q1,CUST-12345,John Smith,welcome-campaign,2024-01-15 +15551234567,welcome-series-q1,CUST-67890,Jane Doe,welcome-campaign,2024-02-20 +447700900123,welcome-series-q1,CUST-11111,Bob Johnson,welcome-campaign,2024-01-30 ``` ### Format Requirements * **Character Encoding:** UTF-8 recommended for international characters * **Delimiter:** Comma (,) by default * **Header Row:** Required - first row must contain column names * **Row Limit:** Up to 100,000 customers per upload *** ## Best Practices ### CSV Preparation **Clean Data:** * Remove duplicate phone numbers * Validate phone number formats before upload * Ensure consistent date formats (YYYY-MM-DD) * Check for special characters in names **Naming Conventions:** * Use descriptive column headers * Avoid spaces in column names (use underscores or camelCase) * Keep field names consistent across uploads **Data Quality:** * Verify phone numbers are active and reachable * Ensure customer consent for outreach * Regular data cleansing to maintain accuracy *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Analytics Source: https://docs.oration.ai/guides/conversations/analytics See exactly how your customers move through conversations — and spot where things can improve. The Analytics page shows you a visual map of how customers interact with your agents and flows. Whether you're debugging a tricky drop-off or tuning a high-performing flow, it gives you the data you need to make better decisions. You can reach it by clicking **Analytics** in the sidebar, under the Conversations heading. ## Overview Analytics uses a **Sankey chart** — a flow diagram where wider paths mean more conversations followed that route — to show you the sequence of events in a conversation. At a glance, you can see: * Where customers engage most * Where they tend to drop off * How often specific events are triggered You can filter the chart by: | Filter | Description | | --------------------- | ------------------------------------------------------------------ | | **Entity type** | Analyze a specific Agent or a Flow | | **Date range** | Focus on a particular timeframe | | **Event definitions** | Agents only — filter by events you've defined, like intent matches | *** ## Agent analytics Agent analytics helps you understand how a specific AI agent handles conversations. In the **Entity selector**, choose the agent you want to analyze. Pick the timeframe you want to look at using the **Date range** selector. Use the **Event definitions** dropdown to focus on specific events. If you leave this empty, the chart defaults to showing system events. ### Configuring event definitions Event definitions let you track meaningful milestones in a conversation — things like a customer confirming an appointment or providing their phone number. Before they show up in analytics, you'll need to set them up in your agent's settings. Navigate to your agent and open its **Settings** page. Select the **Post-call analysis** section. Click to add a new event, then fill out the definition form. Each event definition needs a **Name** and a **Description** of when it should fire. You also choose how Oration detects it: * **AI detection** — Oration's AI reads the conversation transcript and decides whether the event occurred based on your description. Great for nuanced, context-dependent moments. * **Regex pattern** — You provide a regular expression (e.g., `\d{3}-\d{3}-\d{4}`) to match exact text in the transcript. You can choose whether to check messages from the agent, the customer, or both. Use AI detection for open-ended events (like "customer expressed frustration") and regex patterns for structured data (like phone numbers or order IDs). ### Reading the chart The chart traces the path of conversation events between your customers and your agent. Thicker lines mean more events followed that path. Hover over any part of the chart to get an exact count: * **Hover over a node** — see the event name and its **total event count** across all conversations in the selected date range. * **Hover over a link** (the band connecting two nodes) — see the source and target event names, each with a colour indicator, and the **number of events** that moved along that specific path. Use the chart to: * See the most common conversation paths * Find where conversations frequently end * Check how often specific events are triggered *** ## Flow analytics Flow analytics shows you how callers move through your IVR or flow setup — node by node. In the **Entity selector**, choose the flow you want to analyze. Pick the timeframe using the **Date range** selector. Flow analytics doesn't use event definitions — it tracks movement through your flow's nodes instead. ### Reading the chart Instead of conversation events, the chart tracks how callers move through each node in your flow — things like *Play Audio*, *Condition*, or *Transfer*. Every node shows its icon and label so you can orient yourself quickly. Hover over any part of the chart to get an exact count: * **Hover over a node** — see the node name and the **number of conversations** that passed through it in the selected date range. * **Hover over a link** (the band connecting two nodes) — see the source and target node names, each with a colour indicator, and the **number of conversations** that moved along that specific path. Use the chart to: * See what percentage of callers reach each node * Spot where callers drop off before finishing the flow * Confirm your routing logic is working as expected # History Source: https://docs.oration.ai/guides/conversations/history How to review, analyze, and extract insights from your conversation history in Oration AI ## Overview The **History** section in Oration AI provides a comprehensive view of all your past conversations. Here, you can review call details, listen to recordings, analyze transcripts, inspect dynamic variables, and run post-call analysis to extract actionable insights. *** ## 1. Conversation History Overview History Overview The master view displays a list of all calls made by your agents. For each conversation, you can see: * **Agent Name:** The agent who handled the call. * **Created At:** The date and time the call was initiated. * **Talk Time:** Duration of the conversation. * **Customer Phone Number:** The number of the customer involved in the call. * **End Reason:** Why the call ended (e.g., user hangup, completed). * **Conversation Type:** The channel used (e.g., telephony). * **Actions:** Play the call recording or copy the conversation ID for reference. You can filter, sort, and change the view to quickly find the conversations you’re interested in. *** ## 2. Call Transcript and Details Call Transcript and Details Clicking on a conversation opens a detailed view, where you can: * **See Talk Time, End Reason, Status, and Phone Number:** At the top, key call metrics and metadata are displayed. * **Transcript Tab:** Review the full transcript of the conversation, with clear separation between agent and customer messages, including timestamps. * **Playback Controls:** Listen to the call recording directly within the interface. This helps you audit conversations, understand customer interactions, and ensure quality. *** ## 3. Dynamic Variables Dynamic Variables The **Dynamic Variables** tab shows all the placeholders and values used during the conversation. These variables can be referenced in your agent’s prompts and responses to personalize the experience. **Examples:** * `customerName`: The name of the customer. * `amount`: Financial details relevant to the call. Dynamic variables make your agents more context-aware and responsive. *** ## 4. Post Call Analysis Post Call Analysis The **Post Call Analysis** feature lets you extract structured insights from every conversation using AI. * **Is Enabled:** Toggle to automatically run analysis after every call. * **Prompt:** Write a custom prompt to instruct the AI on what to analyze in the transcript, or click **Generate Prompt** for AI assistance. * **Schema:** Define the tags or events you want to capture from the transcript. For each event, specify: * **Type:** The data type (e.g., String). * **Event Name:** The label for the event (e.g., Callback). * **Description:** Describe the event, including scenarios, possible values, criteria, and examples. **Example:**\ To detect if a customer requested a callback, set: * Type: String * Event Name: Callback * Description: "Indicates if the customer asked for a callback. Values: 'yes', 'no'. Criteria: Look for phrases like 'please call me back', 'can you call later', etc. Example: 'I missed your call, can you call me again?'" This structured analysis helps you track key outcomes, monitor agent performance, and identify trends for continuous improvement. *** ## Best Practices * **Regularly review transcripts and recordings** to ensure quality and compliance. * **Leverage dynamic variables** for personalized and context-rich agent responses. * **Use post call analysis** to automate insight extraction and drive data-driven decisions. * **Define clear schemas(event)** for events you want to track, and update them as your business needs evolve. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Core Concepts Source: https://docs.oration.ai/guides/flows/concepts Understand nodes, edges, events, variables, and output handles ## Nodes A **node** is a single unit of work in a flow — playing audio, collecting input, making an API call, or branching based on a condition. Each node has: * **Type** — A unique identifier (e.g., `startNode`, `ivrsMenuNode`) * **Category** — Grouping for the node palette (System, Audio, Logic, Input, Integration, Utility) * **Configuration** — Settings specific to that node type * **Output handles** — Named exit points that connect to the next node *** ## Edges An **edge** is a connection from one node's output handle to another node's input. Edges define the path a call takes through the flow. Each output handle can connect to exactly one target node. *** ## Output handles Output handles are the exit points of a node. They appear as connectable ports on the right side of a node in the visual editor. Each handle represents a possible **outcome** — where the flow goes next. For example, a **Transfer** node has three output handles: * **Successful** — the call was connected * **Timeout** — nobody picked up * **Failed** — the transfer could not be completed You connect each output handle to the next node that should run for that outcome. This is how you build branching logic in a flow. ### Static vs. dynamic handles Some nodes have **static** handles — a fixed set of outputs defined by the node type (e.g., Condition always has `True` and `False`). Other nodes have **dynamic** handles — outputs that change based on configuration: * **IVR Menu** creates a handle for each DTMF key option you configure * **Switch** creates a handle for each case plus a default * **Percent Routing** creates a handle for each route *** ## Variables Variables store data that persists across nodes within a single call. They're used to: * Store caller input (digits, speech transcripts) * Save API response data * Track loop counters * Pass context between nodes ### Setting variables Use the [Set Variable](/guides/flows/nodes/set-variable) node to set values from static text or expressions. Many nodes also automatically set output variables — for example, [Collect Digits](/guides/flows/nodes/collect-digits) stores the collected digits in a variable. ### Referencing variables Reference variables in text fields using double curly braces: ``` Hello {{customer_name}}, your account balance is {{balance}}. ``` *** ## Output variables Certain nodes produce **output variables** — structured data that downstream nodes can reference. For example: | Node | Output variables | | -------------- | -------------------------------- | | Collect Digits | `digits`, `digit_count` | | Speech Input | `transcript`, `confidence` | | API Call | `body`, `status_code`, `headers` | | Database | `rows`, `row_count` | | Play Audio | `duration` | | AI Agent | `transcript` (array) | | Transform | `result` | # AI Agent Source: https://docs.oration.ai/guides/flows/nodes/agent Hand off control to a conversational AI Agent The **AI Agent** node transfers the conversation from the structured IVR flow to a conversational AI Agent powered by a language model. After the agent conversation completes, control returns to the flow. ## Behavior * Invokes the specified AI Agent by ID * The agent handles the conversation autonomously (using its own prompt, tools, and knowledge base) * When the agent conversation ends, the flow resumes via one of three events * Captures the full conversation transcript as an output variable ## Configuration | Parameter | Type | Default | Description | | --------- | ------ | ----------- | --------------------------------------------------------------------------------------- | | `agentId` | string | `"default"` | ID of the AI Agent to invoke. Must match an agent configured in your Oration workspace. | ## Output handles | Handle | Description | | ------------ | ------------------------------------------------------------------- | | **Complete** | Agent conversation finished normally | | **Transfer** | Agent requested a transfer (e.g., caller asked to speak to a human) | | **Error** | Agent encountered an error | ## Output variables | Variable | Type | Description | | ------------ | ----- | -------------------------------------------------------------------------------------- | | `transcript` | array | Array of transcript entries, each containing `timestamp`, `message`, and `messageType` | ## Use cases IVR Menu for department selection → AI Agent for the actual conversation. On `AGENT.TRANSFER`, route to a Transfer node for human escalation. Collect account number via Collect Digits, verify via API Call, then hand off to an AI Agent with the caller's context in variables. After the AI Agent completes, use the transcript output variable in a Transform node to extract key data, then send an SMS summary. # API Call Source: https://docs.oration.ai/guides/flows/nodes/api-call Make HTTP requests to external APIs The **API Call** node sends an HTTP request to an external API and stores the response for use in downstream nodes. ## Behavior * Sends an HTTP request with the configured method, headers, body, and authentication * Retries on failure up to the configured retry count * Stores response body, status code, and headers as output variables * Routes to `Success`, `Error`, or `Timeout` based on the outcome ## Configuration ### Request | Parameter | Type | Default | Options | Description | | ------------- | ------ | ------- | ---------------------------------------------------------- | ---------------------------------------------------------- | | `url` | string | `""` | — | API endpoint URL. Supports `{{variable}}` interpolation. | | `method` | enum | `"GET"` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` | HTTP method | | `requestBody` | string | `""` | — | JSON body template. Supports `{{variable}}` interpolation. | | `headers` | object | `{}` | — | Request headers as key-value pairs | ### Authentication | Parameter | Type | Default | Options | Description | | ----------------- | ------ | ------- | ------------------------------ | ----------------------------------- | | `authType` | enum | `null` | `bearer`, `basic`, `x-api-key` | Authentication type | | `authCredentials` | string | `""` | — | Auth token, credentials, or API key | | `username` | string | `null` | — | Username for basic auth | | `password` | string | `null` | — | Password for basic auth | ### Reliability | Parameter | Type | Default | Range | Description | | --------- | ------ | ------- | ------------ | ----------------------------------- | | `timeout` | number | `10000` | 1,000–60,000 | Request timeout in milliseconds | | `retries` | number | `2` | 0–5 | Number of retry attempts on failure | ## Output handles | Handle | Description | | ----------- | ---------------------------------------------- | | **Success** | Request returned a successful response (2xx) | | **Error** | Request failed (non-2xx status, network error) | | **Timeout** | Request exceeded the configured timeout | ## Output variables | Variable | Type | Description | | ------------- | ------ | --------------------------------------- | | `body` | any | Response body (parsed JSON or raw text) | | `status_code` | number | HTTP response status code | | `headers` | object | Response headers as key-value pairs | ## Example Look up a customer by phone number: ```json theme={null} { "url": "https://api.example.com/customers?phone={{caller_phone}}", "method": "GET", "headers": { "Content-Type": "application/json" }, "authType": "bearer", "authCredentials": "{{api_token}}", "timeout": 5000, "retries": 1 } ``` ## Use cases Look up the caller's account in your CRM by phone number. On success, use the response data to personalize the greeting. POST to a scheduling API with the caller's selected date/time (collected via Collect Digits or Speech Input). POST call data to a webhook endpoint for real-time event processing. Use `{{variable}}` interpolation in the request body. # Collect Digits Source: https://docs.oration.ai/guides/flows/nodes/collect-digits Capture DTMF digit input from the caller The **Collect Digits** node prompts the caller and captures DTMF key presses. It supports input validation, retries, and configurable TTS for prompts. ## Behavior * Plays a prompt message (via TTS or pre-recorded audio) * Listens for DTMF key presses until the terminate key is pressed, max digits are reached, or timeout occurs * Validates input against an optional regex pattern * Retries on invalid input up to the configured retry count * Stores collected digits and count in output variables ## Configuration ### Input settings | Parameter | Type | Default | Range | Description | | ------------------- | ------ | ------- | ----------- | ------------------------------------------- | | `minDigits` | number | `1` | 1–32 | Minimum digits required | | `maxDigits` | number | `16` | 1–32 | Maximum digits accepted | | `terminateKey` | string | `"#"` | single char | Key that ends input early (e.g., `#`) | | `timeout` | number | `10` | 1–60 | Overall timeout in seconds | | `interDigitTimeout` | number | `3` | 1–15 | Max seconds between consecutive key presses | ### Validation | Parameter | Type | Default | Description | | ------------------- | ------ | ------------------------------------ | ----------------------------------------------------------------------- | | `validationPattern` | string | `""` | Regex pattern to validate input (e.g., `^\d{10}$` for 10-digit numbers) | | `validationMessage` | string | `"Invalid format."` | Message played when validation fails | | `retries` | number | `3` | Number of retry attempts on invalid input (1–5) | | `retryMessage` | string | `"Invalid input. Please try again."` | Message played before each retry | ### Prompt | Parameter | Type | Default | Description | | --------------- | ------ | ---------------------------- | --------------------------------------------------------------- | | `promptMessage` | string | `"Please enter your input."` | TTS text for the initial prompt | | `audioUrl` | string | `""` | URL of pre-recorded audio (takes priority over `promptMessage`) | ### TTS settings | Parameter | Type | Default | Description | | ---------- | ------ | ----------------------- | -------------------------- | | `provider` | enum | `"ElevenlabsTTSConfig"` | TTS provider | | `model` | enum | `"eleven_flash_v2_5"` | TTS model | | `voice` | string | `"default"` | Voice identifier | | `voiceId` | string | `""` | Provider-specific voice ID | | `speed` | number | `1.0` | Speech rate (0.5–2.0) | ## Output handles | Handle | Description | | ----------- | ----------------------------------------------- | | **Success** | Valid digits collected | | **Timeout** | No input received within the timeout | | **Invalid** | All retry attempts exhausted with invalid input | ## Output variables | Variable | Type | Description | | ------------- | ------ | -------------------------- | | `digits` | string | The collected DTMF digits | | `digit_count` | number | Number of digits collected | ## Use cases Prompt for a 10-digit account number with `validationPattern: "^\d{10}$"`. On success, pass `{{digits}}` to a Database node. Set `maxDigits: 4`, `terminateKey: "#"`, and `validationPattern: "^\d{4}$"` to collect a 4-digit PIN. Set `minDigits: 10`, `maxDigits: 15` to collect an international phone number. Use the `digits` output variable in an SMS node to send a confirmation. # Condition Source: https://docs.oration.ai/guides/flows/nodes/condition Branch the flow based on conditional logic The **Condition** node evaluates one or more conditions against variables and branches the flow into `True` or `False` paths. ## Behavior * Evaluates a list of conditions using the selected logic operator (`AND` / `OR`) * Routes to `True` if the combined result is truthy, `False` otherwise * Supports 13 comparison operators including regex matching ## Configuration | Parameter | Type | Default | Description | | --------------- | ----- | ------- | ----------------------------------------------------------------------------------- | | `logicOperator` | enum | `"and"` | How to combine multiple conditions: `and` (all must match) or `or` (any must match) | | `conditions` | array | — | List of condition rules (see below) | ### Condition rule Each condition in the `conditions` array has: | Field | Type | Default | Description | | --------------- | ------- | ---------- | ------------------------------------- | | `variable` | string | `""` | Variable name to evaluate | | `operator` | enum | `"equals"` | Comparison operator (see table below) | | `value` | string | `""` | Value to compare against | | `caseSensitive` | boolean | `false` | Enable case-sensitive comparison | ### Operators | Operator | Description | | --------------- | ------------------------------------- | | `equals` | Exact match | | `not_equals` | Not equal | | `contains` | Variable contains the value | | `not_contains` | Variable does not contain the value | | `starts_with` | Variable starts with the value | | `ends_with` | Variable ends with the value | | `greater_than` | Numeric greater than | | `less_than` | Numeric less than | | `greater_equal` | Numeric greater than or equal | | `less_equal` | Numeric less than or equal | | `is_empty` | Variable is empty or undefined | | `is_not_empty` | Variable has a value | | `regex_match` | Variable matches a regular expression | ## Output handles | Handle | Description | | --------- | ------------------------------------------------- | | **True** | All conditions met (AND) or at least one met (OR) | | **False** | Conditions not satisfied | ## Use cases Check if `{{customer_tier}}` equals `"vip"`. Route VIPs to a priority transfer queue and standard customers to the general queue. After Collect Digits, check if `{{digits}}` matches a regex pattern (`regex_match` with `^\d{10}$`) to validate a 10-digit phone number. Combine conditions with `AND`: check that `{{department}}` equals `"sales"` AND `{{business_hours}}` is `"open"`. Only transfer if both are true. # Database Source: https://docs.oration.ai/guides/flows/nodes/database Query or update database records The **Database** node executes SQL queries or stored procedures against a configured database connection and stores the results for use in the flow. ## Behavior * Connects to a pre-configured database using the connection ID * Executes parameterized queries to prevent SQL injection * Stores results in the configured variable name * Routes to `Success`, `Error`, or `No Results` based on the outcome ## Configuration ### Connection & operation | Parameter | Type | Default | Options | Description | | -------------- | ------ | --------- | ------------------------------------------------------- | --------------------------------------------------------- | | `connectionId` | string | `""` | — | Database connection ID (configured in workspace settings) | | `operation` | enum | `"query"` | `query`, `insert`, `update`, `delete`, `call_procedure` | Database operation type | | `query` | string | `""` | — | SQL query or stored procedure name | | `timeout` | number | `10000` | 1,000–60,000 | Query timeout in milliseconds | ### Parameters Each entry in the `parameters` array: | Field | Type | Description | | ------- | ------ | ------------------------------------------------------- | | `name` | string | Parameter name (maps to a placeholder in the query) | | `value` | string | Parameter value. Supports `{{variable}}` interpolation. | | `type` | enum | Data type: `string`, `number`, `boolean`, `date` | ### Results | Parameter | Type | Default | Description | | ---------------- | ------- | ------------- | --------------------------------------------- | | `resultVariable` | string | `"db_result"` | Variable name to store query results | | `singleRow` | boolean | `false` | Return only the first row instead of all rows | ## Output handles | Handle | Description | | -------------- | ------------------------------------------------------ | | **Success** | Query executed successfully with results | | **Error** | Query failed (connection error, syntax error, timeout) | | **No Results** | Query executed but returned no rows | ## Output variables | Variable | Type | Description | | ----------- | ------ | ----------------------------------- | | `rows` | array | Array of result rows | | `row_count` | number | Number of rows returned or affected | ## Example Look up a customer by account number: ```sql theme={null} SELECT name, email, tier FROM customers WHERE account_id = @account_id ``` Parameters: | Name | Value | Type | | ------------ | ------------ | -------- | | `account_id` | `{{digits}}` | `string` | ## Use cases After Collect Digits, query the database for the account. On `DB.NO_RESULTS`, play "Account not found" and retry. On success, greet the customer by name. Use the `insert` operation to log call details (caller ID, timestamp, department) into a calls table at the end of the flow. Set `operation` to `call_procedure` to execute complex business logic like credit checks or eligibility verification. # Date Check Source: https://docs.oration.ai/guides/flows/nodes/date-check Route calls based on specific dates The **Date Check** node evaluates the current date and routes the flow based on whether it matches configured criteria. It can also pause execution with an interruptible wait. ## Behavior * Checks whether the current date matches the configured date criteria * Routes to `True` (match) or `False` (no match) * Optionally waits for a configured duration with an interruptible DTMF key * Can play a message while waiting ## Configuration | Parameter | Type | Default | Range / Options | Description | | --------------- | ------- | ----------- | -------------------- | ------------------------------- | | `duration` | number | `5` | 1–300 | Duration to wait | | `unit` | enum | `"seconds"` | `seconds`, `minutes` | Time unit for the duration | | `interruptible` | boolean | `true` | — | Allow interruption via DTMF | | `interruptKey` | string | `"#"` | — | DTMF key to interrupt | | `playMessage` | boolean | `false` | — | Play a message during the check | | `waitMessage` | string | `""` | — | Message to play | ## Output handles | Handle | Description | | ------------ | -------------------------------------------- | | **Match** | Current date matches the configured criteria | | **No Match** | Current date does not match | ## Use cases Check if today is a promotional date. On match, play a special offer TTS before the main menu. Route differently during holiday seasons. Combine with Time Check for full schedule control. On event dates, route callers to a dedicated event information line instead of the standard menu. # Email Source: https://docs.oration.ai/guides/flows/nodes/email Send an email message during a flow The **Email** node sends an email to a specified recipient. Use it to notify teams, send confirmations, or deliver call summaries. ## Behavior * Sends an email with the configured to, subject, and body fields * Supports `{{variable}}` interpolation in all text fields * Continues the flow on success or routes to the error path on failure ## Configuration | Parameter | Type | Default | Description | | --------- | ------ | ------- | --------------------------------------------------------------- | | `to` | string | `""` | Recipient email address. Supports `{{variable}}` interpolation. | | `subject` | string | `""` | Email subject line | | `body` | string | `""` | Email body content | ## Output handles | Handle | Description | | ----------- | ----------------------- | | **Success** | Email sent successfully | | **Error** | Email delivery failed | ## Use cases Transfer (Failed) → Email to the support team with the caller's phone number and timestamp. After booking via an API Call, send a confirmation email to `{{customer_email}}` with the appointment details. After an AI Agent conversation, extract key details from the transcript and email a summary to the account manager. # End Call Source: https://docs.oration.ai/guides/flows/nodes/end Terminate the call gracefully The **End Call** node terminates the active call. Every flow path must eventually reach an End Call node or a [Transfer](/guides/flows/nodes/transfer) node. ## Behavior * Hangs up the call after an optional delay * Can receive connections from multiple nodes * Has no output handles — it is always a terminal node ## Configuration | Parameter | Type | Default | Range | Description | | ------------- | ------ | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ | | `hangupDelay` | number | `100` | 100–10,000 | Delay in milliseconds before hanging up. Use this to let a final TTS message finish playing before the call disconnects. | ## Use cases Set `hangupDelay` to `2000` (2 seconds) so a goodbye message finishes playing before the line drops. Keep the default `100ms` for scenarios where no final audio is needed (e.g., after a successful transfer). Connect a Time Check (Closed) → TTS ("We're closed, please call back") → End Call with a 3-second delay. # IVR Menu Source: https://docs.oration.ai/guides/flows/nodes/ivr-menu Interactive keypad menu with branching The **IVR Menu** node creates a classic telephone menu — "Press 1 for Sales, Press 2 for Support" — with configurable DTMF options, retries, and barge-in. ## Behavior * Plays a prompt (TTS or audio file) listing the menu options * Listens for DTMF key presses * Routes to the matching option's output handle * On invalid input, plays a retry message and re-prompts * On timeout, follows the timeout path * Output handles are **dynamic** — one per configured DTMF option, plus `Timeout` and `Invalid` ## Configuration ### Prompt | Parameter | Type | Default | Options | Description | | ----------------- | ------ | ---------------------------- | ------------- | ----------------------------------------------------------- | | `promptSource` | enum | `"tts"` | `tts`, `file` | Source of the audio prompt | | `prompt` | string | `"Please select an option."` | — | TTS text for the prompt (used when `promptSource` is `tts`) | | `promptAudioFile` | string | `""` | — | Audio file URL (used when `promptSource` is `file`) | ### Timing & retries | Parameter | Type | Default | Range | Description | | ------------------- | ------ | ---------------------------------------- | ----- | ------------------------------- | | `timeout` | number | `5` | 1–30 | Seconds to wait for input | | `interDigitTimeout` | number | `3` | 1–10 | Seconds between key presses | | `retries` | number | `3` | 1–5 | Retry attempts on invalid input | | `retryMessage` | string | `"Invalid selection. Please try again."` | — | Message played on invalid input | | `timeoutMessage` | string | `"We did not receive your input."` | — | Message played on timeout | ### Interaction | Parameter | Type | Default | Description | | ----------------- | ------- | ------- | -------------------------------------------------------------- | | `bargeIn` | boolean | `true` | Allow caller to press a key before the prompt finishes playing | | `confirmInput` | boolean | `false` | Require the caller to confirm their selection | | `enableStarPound` | boolean | `true` | Enable `*` and `#` as valid menu keys | ### Menu options Each option in the `options` array: | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------ | | `key` | string | DTMF key (`0`–`9`, `*`, `#`) | | `label` | string | Display label | | `action` | enum | Action type: `goto` (go to node), `transfer`, `variable`, `hangup` | | `targetNode` | string | ID of the target node (for `goto` action) | | `event` | string | Event name (auto-generated as `DTMF.{key}`) | ## Output handles Output handles are dynamic based on configured menu options: | Handle | Description | | ----------- | --------------------------------------------------------------- | | **\[Key]** | Caller pressed the corresponding DTMF key (e.g., `1`, `0`, `*`) | | **Timeout** | No input received within timeout | | **Invalid** | All retry attempts exhausted | ## Use cases Configure options for key `1` (Sales), `2` (Support), `3` (Billing), `0` (Operator). Connect each output to the appropriate Transfer node. "Press 1 for English, Press 2 for Spanish." Route to different TTS nodes or AI Agents configured for each language. Chain IVR Menu nodes: Main menu → Sub-menu. Use `*` as a "return to previous menu" key by connecting it back to the parent menu node. # Loop Source: https://docs.oration.ai/guides/flows/nodes/loop Repeat a section of the flow a fixed number of times The **Loop** node repeats a section of the flow a configurable number of times. It maintains an internal counter and provides two exit paths: **Continue** to run the loop body, or **Finish** when the maximum iteration count is reached. ## Behavior * On each entry, compares the internal counter to `maxIterations` * If the counter equals `maxIterations`, routes to **Finish** and resets the counter * Otherwise, increments the counter and routes to **Continue** ## Configuration | Parameter | Type | Default | Range | Description | | --------------- | ------ | ------- | ----- | -------------------------------------- | | `maxIterations` | number | `3` | 1–100 | Maximum number of loop body executions | ## Output handles | Handle | Description | | ------------ | ------------------------------------------------------------------------------ | | **Continue** | Run the loop body — connect this to the first node inside the loop | | **Finish** | Maximum iterations reached — connect this to the node that runs after the loop | Connect the **last node in the loop body** back to the Loop node so the next iteration can run. Loop returns are never inferred automatically — every re-entry must be an explicit edge on the canvas. ## Output variables | Variable | Type | Description | | ----------- | ------- | ------------------------------------------------------------------------------ | | `iteration` | number | Current iteration (1-based while continuing; equals `maxIterations` on Finish) | | `finished` | boolean | `false` on Continue, `true` when exiting via Finish | Reference in downstream nodes as `nodes.{loopNodeId}.iteration` or `nodes.{loopNodeId}.finished`. ## Use cases Loop an IVR Menu so that callers who don't press a valid key hear the menu again, up to `maxIterations` times. Connect the menu timeout path into the Loop node, wire **Continue** back to the menu, and **Finish** to an error message or end call. Loop up to 3 times around an API Call node. Wire **Continue** to the API call and **Finish** to an error handler after all retries are exhausted. Loop to collect multiple data points from the caller (e.g., "Enter item 1... Enter item 2..."). Use `{{nodes.{loopNodeId}.iteration}}` in TTS text to indicate which item number. # Note Source: https://docs.oration.ai/guides/flows/nodes/note Add notes and documentation to the flow canvas The **Note** node is a non-functional node used to annotate the flow canvas. It does not affect call execution — it's purely for documentation and team collaboration. ## Behavior * Displays a styled sticky note on the flow canvas * Does not process calls or emit events * Supports Markdown formatting in the content field * Can be connected to other nodes purely for visual organization ## Configuration | Parameter | Type | Default | Description | | ----------------- | ------ | ----------- | ------------------------------------------- | | `content` | string | `""` | Note content. Supports Markdown formatting. | | `backgroundColor` | string | `"#fef3c7"` | Background color (hex code) | | `textColor` | string | `"#92400e"` | Text color (hex code) | | `author` | string | `""` | Author name | | `createdAt` | string | `""` | Creation timestamp | ## Use cases Add notes explaining the purpose of each section: "This branch handles VIP callers" or "Retry logic for API failures." Use notes with a red background to mark sections that need attention: "TODO: Add Spanish language support." Track recent changes with dated notes: "2024-01-15: Added holiday routing per ticket #1234." # Percent Routing Source: https://docs.oration.ai/guides/flows/nodes/percent-routing Split call traffic across multiple paths by percentage The **Percent Routing** node distributes incoming calls across multiple paths based on configured percentages. Output handles are **dynamic** — one per route. ## Behavior * Assigns each call to a route based on the configured percentage distribution * Percentages **must sum to 100** (validated at save time) * Routes are processed probabilistically — over time, traffic distribution matches the configured percentages ## Configuration | Parameter | Type | Default | Description | | --------- | ----- | ----------------- | ------------------------------------- | | `routes` | array | 2 routes at 50/50 | List of route definitions (see below) | ### Route definition Each entry in `routes`: | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------ | | `label` | string | Display label for the route | | `percentage` | number | Percentage of traffic (0–100). All routes must sum to exactly 100. | ## Output handles Output handles are dynamic — each route generates its own handle: | Handle | Description | | ------------------ | ------------------------------- | | **\[Route Label]** | Call was assigned to this route | **Default routes:** | Handle | Percentage | | ----------- | ---------- | | **Route A** | 50% | | **Route B** | 50% | ## Use cases Split traffic 50/50 between two different greeting scripts or menu structures to measure which performs better. Route 10% of calls to a new AI Agent flow and 90% to the existing IVR. Increase the percentage as confidence grows. Split calls across three regional support centers: 40% North America, 35% Europe, 25% Asia. # Play Audio Source: https://docs.oration.ai/guides/flows/nodes/play-audio Play a pre-recorded audio file to the caller The **Play Audio** node plays an audio file from a URL to the caller. ## Behavior * Streams audio from the configured URL * Optionally loops the audio a specified number of times * Emits `AUDIO.COMPLETE` when playback finishes or `AUDIO.ERROR` on failure ## Configuration | Parameter | Type | Default | Range | Description | | ------------- | ------- | ------- | ----- | ------------------------------------------------------------ | | `audioSource` | enum | `"url"` | `url` | Audio source type | | `audioUrl` | string | `""` | — | URL of the audio file to play | | `loop` | boolean | `false` | — | Enable looping playback | | `loopCount` | number | `1` | 1–10 | Number of times to loop (only applies when `loop` is `true`) | ## Output handles | Handle | Description | | ------------ | ---------------------------------------------------------------- | | **Complete** | Audio finished playing — flow continues to the next node | | **Error** | Playback failed (invalid URL, network error, unsupported format) | ## Output variables | Variable | Type | Description | | ---------- | ------ | -------------------------------------------- | | `duration` | number | Duration of the played audio in milliseconds | ## Use cases Enable `loop` with `loopCount: 5` to play background music while the caller waits in a queue. Play a pre-recorded compliance message before connecting to an agent. Use the `duration` output variable to set a matching `hangupDelay` on the End Call node. Use a Switch node on the caller's language, then route to different Play Audio nodes with region-specific audio URLs. # Set Variable Source: https://docs.oration.ai/guides/flows/nodes/set-variable Set or compute variables for use in the flow The **Set Variable** node assigns a value to a named variable. The value can be a static string or a computed expression. ## Behavior * Sets the named variable to the configured value * Supports both static values and dynamic expressions * The variable is available to all downstream nodes via `{{variableName}}` * Emits `SET_VARIABLE.SUCCESS` on completion or `SET_VARIABLE.ERROR` on failure ## Configuration | Parameter | Type | Default | Options | Description | | -------------- | ------ | ---------- | ---------------------- | ----------------------------------------------------------- | | `variableName` | string | `""` | — | Name of the variable to set | | `source` | enum | `"static"` | `static`, `expression` | How the value is determined | | `value` | string | `""` | — | Static value (used when `source` is `static`) | | `expression` | string | `""` | — | Expression to evaluate (used when `source` is `expression`) | ### Source types | Source | Description | | ------------ | ---------------------------------------------------------------------------------------- | | `static` | Set the variable to a literal string value | | `expression` | Evaluate an expression (e.g., concatenation, arithmetic, or referencing other variables) | ## Output handles | Handle | Description | | ----------- | ------------------------------------------------- | | **Success** | Variable set successfully | | **Error** | Failed to set variable (e.g., invalid expression) | ## Use cases Set `language` to `"en"` at the start of the flow. Override it later based on caller input. Use `expression` source to combine variables: set `greeting` to `"Hello, " + {{customer_name}}`. Set a `status` variable at different points in the flow (e.g., `"verified"`, `"transferred"`) for use in API calls or logging. # SMS Source: https://docs.oration.ai/guides/flows/nodes/sms Send an SMS message during a flow The **SMS** node sends a text message to a phone number. Use it to deliver confirmations, one-time codes, or follow-up links. ## Behavior * Sends an SMS to the configured phone number with the specified message * Supports `{{variable}}` interpolation in both fields * Continues the flow on success or routes to the error path on failure ## Configuration | Parameter | Type | Default | Description | | ------------- | ------ | ------- | ----------------------------------------------------------------------------------------- | | `phoneNumber` | string | `""` | Recipient phone number. Supports `{{variable}}` interpolation (e.g., `{{caller_phone}}`). | | `message` | string | `""` | SMS message body | ## Output handles | Handle | Description | | ----------- | --------------------- | | **Success** | SMS sent successfully | | **Error** | SMS delivery failed | ## Use cases Generate a code via Set Variable, send it via SMS, then ask the caller to enter it using Collect Digits for verification. After the call ends, send a link to a satisfaction survey or a summary of the conversation. While a caller waits in a queue, send an SMS with estimated wait time and a callback option link. # Speech Input Source: https://docs.oration.ai/guides/flows/nodes/speech-input Capture voice input using speech recognition The **Speech Input** node captures the caller's spoken words using automatic speech recognition (ASR) and stores the transcript and confidence score. ## Behavior * Listens for the caller's speech using the configured ASR model * Returns a transcript with a confidence score * If confidence is below the threshold, emits `SPEECH.NO_MATCH` * Supports grammar constraints and recognition hints for improved accuracy * Falls back to DTMF input if enabled ## Configuration ### Recognition | Parameter | Type | Default | Range / Options | Description | | --------------------- | --------- | ----------- | ---------------------------------------------- | -------------------------------------------------------------------- | | `language` | string | `"en-US"` | — | Language code for recognition | | `model` | enum | `"default"` | `default`, `enhanced`, `medical`, `phone_call` | ASR model selection | | `confidenceThreshold` | number | `0.7` | 0–1 | Minimum confidence score to accept (below this triggers `NO_MATCH`) | | `grammar` | string | `""` | — | Grammar constraint (SRGS format or plain text word list) | | `hints` | string\[] | `[]` | — | Recognition hints — words or phrases the ASR model should prioritize | | `partialResults` | boolean | `false` | — | Return partial (interim) results during recognition | ### Timing & retries | Parameter | Type | Default | Range | Description | | ---------------- | ------ | ------- | ----- | ------------------------------------------------- | | `timeout` | number | `10` | 1–60 | Maximum listening duration in seconds | | `silenceTimeout` | number | `3` | 1–15 | Stop listening after this many seconds of silence | | `retries` | number | `2` | 1–5 | Number of retry attempts on no match | ### Output & fallback | Parameter | Type | Default | Description | | ---------------- | ------- | ---------------- | --------------------------------------------- | | `variableName` | string | `"speech_input"` | Variable to store the recognized transcript | | `fallbackToDTMF` | boolean | `true` | Accept DTMF input if speech recognition fails | ### ASR models | Model | Best for | | ------------ | ---------------------------------------------- | | `default` | General-purpose recognition | | `enhanced` | Higher accuracy with larger vocabulary | | `medical` | Medical terminology and clinical conversations | | `phone_call` | Optimized for telephony audio quality | ## Output handles | Handle | Description | | ------------ | ---------------------------------------------------------------------- | | **Success** | Speech recognized with confidence above threshold | | **No Match** | Speech detected but confidence below threshold, or no matching grammar | | **Timeout** | No speech detected within timeout | ## Output variables | Variable | Type | Description | | ------------ | ------ | ---------------------------------- | | `transcript` | string | The recognized speech text | | `confidence` | number | Recognition confidence score (0–1) | ## Use cases Set `hints` to common first names and `confidenceThreshold: 0.6` for flexible name recognition. Store the result in `{{customer_name}}`. Set `grammar` to `"yes no"` and `model: "phone_call"` for reliable binary responses over phone lines. Use `model: "medical"` with `hints` for medication names and symptoms. Set `silenceTimeout: 5` to give patients time to think. # Start Source: https://docs.oration.ai/guides/flows/nodes/start Entry point of every flow The **Start** node is the entry point of every flow. When a call arrives, execution begins here and follows the single outgoing edge to the next node. ## Behavior * Every flow must have exactly **one** Start node * The Start node has a single output handle (`Start`) that emits the `START.NEXT` event * It cannot receive incoming connections — it is always the first node ## Configuration The Start node requires no configuration. It serves purely as the flow's entry point. ## Output handles | Handle | Description | | --------- | ------------------------------------------------------------------- | | **Start** | The single exit point — connect this to the first node in your flow | ## Use cases Connect Start → Text to Speech (welcome message) → IVR Menu (department selection). Connect Start → Time Check to route callers differently during open vs. closed hours. Connect Start → IVR Menu for language selection → AI Agent for the conversation. # Sub Flow Source: https://docs.oration.ai/guides/flows/nodes/sub-flow Execute another published flow as a reusable step in your main flow The **Sub Flow** node allows you to embed and execute another published flow as a nested component within your main flow. This enables code reuse, modular design, and simplified management of complex flow logic. ## Behavior * Executes the referenced flow from start to end * Inherits all dynamic variables and context from the parent flow * Preserves the caller's context (phone number, conversation metadata, etc.) * Waits for the sub-flow to complete before continuing to the next node in the main flow * Supports arbitrary nesting depth (sub-flows within sub-flows) * Automatically flattens during flow initialization for seamless execution ## When to use Use Sub Flow nodes when you want to: * **Reuse common sequences** across multiple flows (e.g., authentication, IVR menu trees) * **Organize complex logic** into manageable, testable units * **Simplify maintenance** by updating shared flows in one place * **Compose flows dynamically** without duplicating node configurations * **Share context** between flows (e.g., pass user data, authentication results, or preferences) ## Configuration | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------- | | `flowId` | string | Yes | The ID of the published flow to execute as a sub-flow | ## How it works ### Flow Resolution During conversation initialization, the system performs automatic **flow resolution**: 1. **Discovery** — Scans the main flow for all `Sub Flow` node references 2. **Fetching** — Retrieves the referenced flows from the database (iteratively, handling nested sub-flows) 3. **Flattening** — Merges all sub-flow nodes and edges directly into the main flow 4. **Execution** — The XState actor runs one unified, flat flow with no sub-flow overhead ### Node Prefixing When a sub-flow is embedded, all of its internal nodes are prefixed with the `Sub Flow` node's ID to ensure uniqueness. This allows: * The same sub-flow to be embedded multiple times without ID collisions * Deep nesting (sub-flow-of-sub-flow) with clear node identity chains * Proper state tracking for each embedded instance ### Example Prefixing ``` Main Flow: [subflow-1] → mainFlow subFlow node → (embeds flow-auth) After flattening: subflow-1__tts-node subflow-1__collect-digits subflow-1__condition-node ... ``` ### Agent Hydration If a sub-flow contains `Agent` nodes, they are automatically discovered and hydrated during flow initialization. This means: * Agent configurations are loaded for all nested agent nodes * Tools, LLM settings, and RAG configurations are applied before the flow runs * The flow sees all agent nodes—regardless of nesting—as part of the unified graph ## Output handles | Handle | Description | | ------------ | --------------------------------------------------------------------------------------------- | | **Complete** | Sub-flow executed successfully and reached an end node — main flow continues to the next node | | **Error** | Sub-flow encountered an error or reached an error state | ## Limitations and considerations The system prevents cycles during flow initialization. If flow A references flow B and flow B references flow A, the conversation will fail at startup with a clear error message. Plan your flow hierarchy to avoid circular dependencies. A sub-flow cannot contain only `Start` and `End` nodes—it must have at least one executable node (e.g., TTS, Agent, API Call). This ensures the flattened graph remains valid. Flow flattening is performed once at initialization time. Arbitrarily deep nesting (A → B → C → D) is supported and has minimal runtime overhead after flattening completes. Only flows that are saved and published can be referenced by a `Sub Flow` node. Unsaved drafts cannot be used. Sub-flows share the same variable context as the parent flow. Any variables set by a sub-flow are visible to subsequent nodes in the main flow. There is no variable scope isolation. ## Use cases Create a dedicated flow (e.g., `authenticate-customer`) that collects PIN, verifies it, and sets an `authenticated` flag. Embed this flow at the start of multiple customer-facing flows to ensure consistent authentication logic. **Flow structure:** ``` Main Flow → Sub Flow (authenticate-customer) → [Authenticated branch logic] ``` Create a modular menu hierarchy where each level is a separate flow: * `main-menu` — Primary options * `sales-menu` — Sales department options * `support-menu` — Support department options The main flow embeds `main-menu`, which in turn embeds `sales-menu` or `support-menu` based on the caller's selection. **Flow structure:** ``` Main Flow → Sub Flow (main-menu) → IVR Menu [1: Sales, 2: Support] → Switch node routing to: → Sub Flow (sales-menu) → Sub Flow (support-menu) ``` Create a `pre-agent-context` flow that gathers caller information (order number, issue type) and formats it for the agent. Embed this before an `Agent` node to ensure agents always receive pre-qualified context. **Flow structure:** ``` Main Flow → Sub Flow (pre-agent-context) [Collects and formats context] → Agent Node [Receives formatted context] ``` Create a dedicated `after-hours-routing` flow that checks the time and routes to voicemail or an external service. Embed this at the end of your main flow to provide consistent off-hours behavior. **Flow structure:** ``` Main Flow → Condition [Operating hours?] → If YES: Normal call handling → If NO: Sub Flow (after-hours-routing) ``` Create language-specific flows (`flow-english`, `flow-spanish`, `flow-french`) with the same structure but localized audio/text. Use a Switch node on `caller.language` to embed the appropriate flow. **Flow structure:** ``` Main Flow → Speech Input [Detect language] → Switch on language → Sub Flow (flow-english) → Sub Flow (flow-spanish) → Sub Flow (flow-french) ``` ## Technical details ### Flow Flattening Algorithm Sub-flows are resolved and flattened during conversation initialization (before the XState actor starts). The process: 1. **Scope-bound fetch** — Only flows referenced in the current conversation's main flow are fetched; this prevents unnecessary database queries 2. **Recursive resolution** — Nested sub-flows are discovered and fetched in an iterative process until no new flows are found 3. **Edge rewriting** — Incoming and outgoing edges are re-routed to maintain flow continuity: * Main flow edges targeting the sub-flow node now target the sub-flow's first real node * Sub-flow exit edges now target the main flow's original target 4. **ID prefixing** — All sub-flow nodes are prefixed to avoid collisions 5. **Flattened result** — A single, unified `FlowSchema` with no `Sub Flow` nodes is passed to the XState actor ### Error Handling The system throws an error at initialization time if: * A referenced flow does not exist in the database * A flow is missing its `flowId` configuration * A cycle is detected (A → B → A) * A sub-flow is missing its `Start` or `End` node * A sub-flow contains only `Start` and `End` with no intermediate nodes Early error detection prevents runtime failures and makes debugging easier. ## Best practices **Organize flows hierarchically** — Create a naming convention (e.g., `base-*` for reusable flows, `main-*` for entry points) to make your flow library self-documenting. **Keep sub-flows focused** — Each sub-flow should have a single, well-defined purpose. Large, multi-purpose sub-flows are harder to test and reuse. **Test sub-flows independently** — Before embedding a sub-flow, test it as a standalone flow to ensure it works correctly. **Use descriptive flow names** — Instead of `flow-123`, use `authenticate-customer` or `qualify-sales-lead` so the purpose is clear in the editor. **Document shared context** — If a sub-flow expects or sets specific variables, document them clearly so integrators know what to provide and what they'll receive. # Switch Source: https://docs.oration.ai/guides/flows/nodes/switch Multi-way branch based on a variable's value The **Switch** node evaluates a variable against multiple cases and routes the flow to the matching branch. It works like a `switch/case` statement — if no case matches, the flow takes the `Default` path. ## Behavior * Reads the specified variable's value * Compares against each case using the configured match type * Routes to the first matching case, or `Default` if none match * Output handles are **dynamic** — one handle per case plus a `Default` handle ## Configuration | Parameter | Type | Default | Options | Description | | --------------- | --------- | --------- | ---------------------------- | --------------------------------------------------------------------------- | | `variable` | string | `""` | — | Variable name to evaluate | | `matchType` | enum | `"exact"` | `exact`, `contains`, `regex` | How to compare variable value against cases | | `caseSensitive` | boolean | `false` | — | Enable case-sensitive matching | | `cases` | string\[] | `[]` | — | List of case values to match against. Each case generates an output handle. | ### Match types | Type | Description | | ---------- | --------------------------------------------------------- | | `exact` | Variable value must exactly equal the case value | | `contains` | Variable value must contain the case value as a substring | | `regex` | Case value is treated as a regular expression pattern | ## Output handles Switch output handles are dynamic — each case generates a handle, plus a `Default` handle for the fallback: | Handle | Description | | ----------------- | ---------------------------------------------------------- | | **\[Case Value]** | Flow follows this path when the variable matches this case | | **Default** | Flow follows this path when no case matches | ## Use cases Switch on `{{language}}` with cases `en`, `es`, `fr`, and a `Default` fallback. Route each to a language-specific TTS greeting. After an IVR Menu collects a department name via speech input, switch on the transcript to route to Sales, Support, or Billing queues. After an API Call, switch on `{{status_code}}` with cases `200`, `404`, `500` to handle different response scenarios. # Time Check Source: https://docs.oration.ai/guides/flows/nodes/time-check Route calls based on business hours, custom schedules, or holidays The **Time Check** node evaluates the current time against business hours, custom time ranges, or holiday calendars and routes the call accordingly. ## Behavior * Checks the current time in the configured timezone * Compares against business hours, custom ranges, or a holiday calendar * Routes to `Open`, `Closed`, or `Holiday` based on the result ## Configuration | Parameter | Type | Default | Options / Range | Description | | -------------------- | --------- | --------------------------------- | ------------------------------------- | -------------------------------------------------------- | | `timezone` | string | `"UTC"` | — | IANA timezone (e.g., `America/New_York`, `Asia/Kolkata`) | | `checkType` | enum | `"business_hours"` | `business_hours`, `custom`, `holiday` | Type of time check to perform | | `businessHoursStart` | string | `"09:00"` | HH:mm | Business open time | | `businessHoursEnd` | string | `"17:00"` | HH:mm | Business close time | | `businessDays` | string\[] | `["mon","tue","wed","thu","fri"]` | `mon`–`sun` | Days the business is open | | `customRanges` | array | `[]` | — | Custom time ranges (see below) | | `holidayCalendar` | string | `""` | — | Holiday calendar identifier | | `closedMessage` | string | `"We are currently closed..."` | — | Message to play when closed | ### Custom time range Each entry in `customRanges`: | Field | Type | Description | | ----------- | --------- | -------------------------- | | `id` | string | Unique range identifier | | `label` | string | Display label | | `startTime` | string | Start time (HH:mm) | | `endTime` | string | End time (HH:mm) | | `days` | string\[] | Days of week (`mon`–`sun`) | ## Output handles | Handle | Description | | ----------- | ----------------------------------------------------- | | **Open** | Current time is within business hours / custom range | | **Closed** | Current time is outside business hours / custom range | | **Holiday** | Current date is a holiday | ## Use cases Start → Time Check → (Open) Transfer to queue, (Closed) TTS closed message → Voicemail → End Call. Use `custom` check type with ranges for weekday 9–17 and weekend 10–14 to handle different schedules. Configure a holiday calendar. On holidays, play a special message and offer voicemail instead of transferring. # Transfer Source: https://docs.oration.ai/guides/flows/nodes/transfer Transfer the call to an agent, queue, or external number The **Transfer** node routes the active call to a human agent, a call queue, an external phone number, or a SIP endpoint. ## Behavior * Initiates a call transfer to the configured destination * Waits up to the configured timeout for the transfer to complete * Emits one of three events based on the outcome * Optionally records the transferred call and whispers context to the receiving agent ## Configuration | Parameter | Type | Default | Options / Range | Description | | ---------------- | ------- | ---------- | ------------------------------------ | ----------------------------------------------------------- | | `transferType` | enum | `"queue"` | `queue`, `direct`, `external`, `sip` | Destination type | | `phoneNumber` | string | `""` | — | Target phone number (for `external` transfers) | | `sipUri` | string | `""` | — | Target SIP URI (for `sip` transfers) | | `queueName` | string | `""` | — | Target queue name (for `queue` transfers) | | `agentId` | string | `""` | — | Target agent ID (for `direct` transfers) | | `priority` | enum | `"normal"` | `low`, `normal`, `high`, `urgent` | Transfer priority level | | `timeout` | number | `60` | 10–300 | Ring timeout in seconds | | `whisperMessage` | string | `""` | — | Message whispered to the agent before connecting the caller | | `recordCall` | boolean | `true` | — | Record the transferred call | ### Transfer types Route to a named call queue. The call is distributed to the next available agent in the queue based on priority. Transfer directly to a specific agent by ID. Useful for VIP routing or callback scenarios. Dial an external phone number. Use for transferring to third-party services or non-agent destinations. Route via SIP URI for enterprise telephony integrations. ## Output handles | Handle | Description | | -------------- | --------------------------------------------------------------- | | **Successful** | Transfer completed — the caller is connected to the destination | | **Timeout** | No answer within the configured timeout | | **Failed** | Transfer failed (destination unavailable, network error, etc.) | ## Use cases IVR Menu → Transfer (queue: "sales"). On timeout, transfer to a backup external number. On failure, play an apology and end the call. Use a Condition node to check a customer tier variable. If VIP, transfer directly to a specific agent with `priority: "urgent"` and a whisper message. Time Check (Closed) → Transfer (external) to an after-hours answering service. # Transform Source: https://docs.oration.ai/guides/flows/nodes/transform Transform data values with string, number, and JSON operations The **Transform** node modifies a variable's value using one of 12 built-in transformation types. It reads from an input variable, applies the transformation, and stores the result. ## Behavior * Reads the value from the specified input variable * Applies the selected transformation with optional parameters * Stores the result in the `result` output variable * Routes to `Success` or `Error` based on the outcome ## Configuration | Parameter | Type | Default | Description | | --------------- | ------ | ------------ | ---------------------------------------------------- | | `inputVariable` | string | `""` | Variable to read the input value from | | `transformType` | enum | `"to_upper"` | Transformation to apply (see table below) | | `params` | object | `{}` | Additional parameters specific to the transform type | ### Transform types | Type | Description | Relevant params | | ---------------- | ------------------------------------- | ------------------------------------------- | | `to_upper` | Convert to uppercase | — | | `to_lower` | Convert to lowercase | — | | `trim` | Remove leading/trailing whitespace | — | | `replace` | Find and replace text | `pattern`, `replacement` | | `substring` | Extract a portion of the string | `startIndex`, `endIndex` | | `split` | Split string into an array | `separator` | | `join` | Join array elements into a string | `separator` | | `json_parse` | Parse a JSON string into an object | — | | `json_stringify` | Convert an object to a JSON string | — | | `number_format` | Format a number with decimal places | `numberFormat` (0–5 decimal places) | | `date_format` | Format a date value | `dateFormat` (`ISO`, `locale`, `timestamp`) | | `regex_extract` | Extract text matching a regex pattern | `pattern` | ### Params reference | Param | Type | Description | | -------------- | ------ | --------------------------------------------------------------- | | `pattern` | string | Regex pattern or search string (for `replace`, `regex_extract`) | | `replacement` | string | Replacement string (for `replace`) | | `separator` | string | Delimiter (for `split`, `join`) | | `startIndex` | number | Start index for `substring` | | `endIndex` | number | End index for `substring` | | `dateFormat` | enum | Date format: `ISO`, `locale`, `timestamp` | | `numberFormat` | number | Decimal places (0–5) for `number_format` | ## Output handles | Handle | Description | | ----------- | ------------------------------------------------ | | **Success** | Transformation completed successfully | | **Error** | Transformation failed (e.g., invalid input type) | ## Output variables | Variable | Type | Description | | -------- | ---- | --------------------- | | `result` | any | The transformed value | ## Use cases After Speech Input, use `trim` then `to_lower` to clean up the transcript before using it in a Condition node. After an API Call, use `json_parse` to convert the response body string into an object, then use `regex_extract` to pull specific fields. Use `number_format` with `numberFormat: 2` to display an account balance as `1234.56` in a TTS message. # Text to Speech Source: https://docs.oration.ai/guides/flows/nodes/tts Convert text to speech with configurable voice and delivery The **Text to Speech** (TTS) node converts text into spoken audio and plays it to the caller in real time. ## Behavior * Sends text to the configured TTS provider * Streams the synthesized audio to the caller * Supports variable interpolation in the text (e.g., `{{customer_name}}`) * Emits `TTS.END` on completion or `TTS.ERROR` on failure ## Configuration | Parameter | Type | Default | Range / Options | Description | | ---------- | ------ | ----------------------- | --------------------------------------- | --------------------------------------------------------- | | `text` | string | `""` | — | The text to speak. Supports `{{variable}}` interpolation. | | `provider` | enum | `"ElevenlabsTTSConfig"` | Provider-specific | TTS provider to use | | `model` | enum | `"eleven_flash_v2_5"` | Model-specific | TTS model identifier | | `voice` | string | `"default"` | — | Voice identifier | | `voiceId` | string | `""` | — | Specific voice ID from the provider | | `language` | string | `"en"` | — | Language code (e.g., `en`, `en-US`, `es`) | | `speed` | number | `1.0` | 0.5–2.0 | Speech rate multiplier | | `pitch` | number | `1.0` | 0.5–2.0 | Speech pitch multiplier | | `emphasis` | enum | `"moderate"` | `none`, `moderate`, `strong`, `reduced` | Emphasis level for speech delivery | ## Output handles | Handle | Description | | --------- | ----------------------------------------------------------- | | **End** | Speech playback completed — flow continues to the next node | | **Error** | TTS generation or playback failed | ## Use cases Set `text` to `"Hello {{customer_name}}, thank you for calling."` after looking up the caller in a Database node. Set `speed: 0.8` for complex instructions that callers need time to process. Use a Switch on language preference, then route to separate TTS nodes with matching `language` and `voiceId` configurations. # Voicemail Source: https://docs.oration.ai/guides/flows/nodes/voicemail Record voicemail with transcription and notifications The **Voicemail** node records a voicemail from the caller, optionally transcribes it, and sends notifications via email or webhook. ## Behavior * Plays a custom greeting (if configured), then a beep * Records the caller's message up to the configured max duration * Stops recording on silence timeout * Optionally transcribes the recording * Sends notifications with the recording and transcript ## Configuration | Parameter | Type | Default | Range | Description | | ----------------------- | ------- | ------- | ------ | ---------------------------------------------------------------------------- | | `greeting` | string | `""` | — | Custom greeting message played before the beep. Leave empty for no greeting. | | `maxDuration` | number | `120` | 10–600 | Maximum recording duration in seconds | | `beepEnabled` | boolean | `true` | — | Play a beep tone before recording starts | | `transcribeEnabled` | boolean | `true` | — | Transcribe the voicemail using speech-to-text | | `transcriptionLanguage` | string | `"en"` | — | Language code for transcription (e.g., `en`, `es`, `fr`) | | `notifyEmail` | string | `""` | — | Email address to notify when a voicemail is received | | `notifyWebhook` | string | `""` | — | Webhook URL to POST voicemail data to | | `allowRerecord` | boolean | `true` | — | Allow the caller to re-record their message | | `silenceTimeout` | number | `5` | 1–30 | Stop recording after this many seconds of silence | ## Use cases Time Check (Closed) → TTS ("Leave a message after the beep") → Voicemail → End Call. Configure `notifyEmail` to send the recording to your team. Transfer (Timeout/Failed) → Voicemail. When no agent is available, capture the caller's message and notify via webhook for CRM integration. Use a Switch node on the caller's language preference, then route to separate Voicemail nodes with matching `transcriptionLanguage` values. # Wait / Delay Source: https://docs.oration.ai/guides/flows/nodes/wait Pause the flow for a specified duration The **Wait** node pauses flow execution for a configurable duration. Optionally, it can play a message while waiting and allow the caller to interrupt with a DTMF key press. ## Behavior * Pauses execution for the configured duration * Optionally plays a message during the wait * Can be interrupted by the caller pressing a DTMF key * Emits `WAIT.COMPLETE` when the wait finishes or `WAIT.ERROR` on failure ## Configuration | Parameter | Type | Default | Range / Options | Description | | --------------- | ------- | ----------- | -------------------- | ----------------------------------------------------------------- | | `duration` | number | `5` | 1–300 | Duration to wait | | `unit` | enum | `"seconds"` | `seconds`, `minutes` | Time unit for the duration | | `interruptible` | boolean | `true` | — | Allow the caller to interrupt the wait by pressing a DTMF key | | `interruptKey` | string | `"#"` | — | DTMF key that interrupts the wait | | `playMessage` | boolean | `false` | — | Play a message during the wait | | `waitMessage` | string | `""` | — | Text message to play while waiting (requires `playMessage: true`) | ## Output handles | Handle | Description | | ------------ | ------------------------------------------- | | **Complete** | Wait duration elapsed or caller interrupted | | **Error** | An error occurred during the wait | ## Use cases Add a 2-second wait between a TTS message and a Transfer node to give the caller time to hear the full message. Set `duration: 30`, `unit: "seconds"`, `playMessage: true`, and `waitMessage: "Please hold while we connect you."` to play a hold message. Wait 60 seconds with `interruptKey: "*"`. If the caller presses `*`, skip the wait and proceed immediately to the next node. # Flows Source: https://docs.oration.ai/guides/flows/overview Build programmable IVR call flows with a visual, drag-and-drop editor ## What are Flows? Flows let you design and deploy interactive voice response (IVR) systems using a visual, node-based editor. Each flow is a directed graph of **nodes** connected by **edges** — defining exactly how a call is handled from start to finish. Unlike conversational AI agents that rely on language models for open-ended dialogue, flows give you **deterministic, predictable call routing** with precise control over every step. Every call follows a defined path — no ambiguity in how calls are handled. Drag-and-drop nodes, connect edges, and configure everything visually. Hand off to AI Agents mid-flow for natural conversation, then return to structured routing. Connect to APIs, databases, CRMs, and send emails or SMS — all within a flow. *** ## When to use Flows vs. AI Agents | | **Flows** | **AI Agents** | | ----------------- | --------------------------------------------------- | -------------------------------------- | | **Best for** | Structured IVR menus, call routing, data collection | Open-ended conversations, complex Q\&A | | **Control** | Deterministic — every path is explicitly defined | Probabilistic — LLM decides responses | | **Input** | DTMF keypresses, speech recognition | Natural language | | **Extensibility** | Nodes for APIs, databases, transfers | Tools, knowledge bases | **Tip:** Combine both. Use a flow for initial call routing (language selection, department menu) and hand off to an AI Agent for the actual conversation. *** ## Quick start Navigate to **Flows** in the sidebar and click **Create Flow**. Give it a name and description. Every flow starts with a **Start** node. Drag nodes from the palette onto the canvas — add an **IVR Menu**, a **Time Check**, or a **Text to Speech** node. Draw edges between output handles and the next node's input. Each output handle represents an event (e.g., a key press, a timeout, or a successful API call). Click any node to open its configuration panel. Set prompts, timeouts, API endpoints, transfer destinations, and more. Every path must end with an **End Call** node or a **Transfer** node. The editor validates this for you. Assign the flow to a phone number and publish. Incoming calls will be routed through your flow. *** ## Node categories Flows offers six categories of nodes. Click through to learn about each one. | Category | Purpose | Nodes | | --------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **System** | Flow lifecycle — start, end, transfer, voicemail, reusable sub-flows | [Start](/guides/flows/nodes/start), [End](/guides/flows/nodes/end), [Transfer](/guides/flows/nodes/transfer), [Voicemail](/guides/flows/nodes/voicemail), [Sub Flow](/guides/flows/nodes/sub-flow) | | **Audio** | Play audio or speak text to the caller | [Play Audio](/guides/flows/nodes/play-audio), [Text to Speech](/guides/flows/nodes/tts) | | **Logic** | Control flow with conditions, loops, and routing | [Condition](/guides/flows/nodes/condition), [Switch](/guides/flows/nodes/switch), [Loop](/guides/flows/nodes/loop), [Wait](/guides/flows/nodes/wait), [Time Check](/guides/flows/nodes/time-check), [Date Check](/guides/flows/nodes/date-check), [Percent Routing](/guides/flows/nodes/percent-routing) | | **Input** | Collect caller input via DTMF or speech | [Collect Digits](/guides/flows/nodes/collect-digits), [IVR Menu](/guides/flows/nodes/ivr-menu), [Speech Input](/guides/flows/nodes/speech-input) | | **Integration** | Connect to external systems | [AI Agent](/guides/flows/nodes/agent), [API Call](/guides/flows/nodes/api-call), [Database](/guides/flows/nodes/database), [Email](/guides/flows/nodes/email), [SMS](/guides/flows/nodes/sms) | | **Utility** | Internal tools for flow development | [Note](/guides/flows/nodes/note), [Set Variable](/guides/flows/nodes/set-variable), [Transform](/guides/flows/nodes/transform) | # Welcome to Oration Source: https://docs.oration.ai/guides/get-started/introduction Oration is the enterprise platform for building, deploying, and managing AI voice agents that handle real customer conversations at scale. Agent Details Oration gives your team the tools to build AI voice agents that speak naturally, understand context, and resolve customer issues—without a human on the line. From inbound support to outbound campaigns, every conversation is handled consistently, intelligently, and on brand. ## What you can build Answer calls, qualify leads, resolve support queries, and route customers—without hold times or transfers. Run automated outbound calls at scale for collections, reminders, surveys, and follow-ups. Design branching call logic with conditions, time checks, and multi-step flows using a visual editor. Score every conversation automatically with custom scorecards and evals to maintain quality at scale. ## Get started Create your first AI voice agent and take a call in minutes. Learn the core concepts behind how Oration agents work. ## Explore the platform Configure your agent's persona, instructions, voice, and tools. Build call logic visually with nodes for branching, conditions, and integrations. Upload customer lists and launch outbound calling campaigns. Teach your agents your terminology, tone, and coaching preferences. Track call outcomes, agent performance, and conversation trends. Let the voice agent ask a human colleague for help without transferring the call. Trigger calls, retrieve transcripts, and integrate Oration into your stack. Need help? Reach out to our team at [developers@oration.ai](mailto:developers@oration.ai) # Quickstart Source: https://docs.oration.ai/guides/get-started/quickstart Start building awesome AI agents in under 5 minutes Welcome to Oration AI\\! This quickstart guide will help you set up your account, create your first AI agent, and get it up and running in no time. ## Setup your Oration AI Account & Workspace Getting started with Oration AI is quick and easy. Follow these steps to create your account and set up your workspace: 1. Visit the Oration AI website and click on the "Sign Up" or "Get Started" button. 2. You'll see a login screen asking "Hello, who's this?". Enter your email address in the provided field. 3. Choose your preferred sign-in method: * Click the "Sign in" button to use your email * Select "Sign in with a password" if you have an existing account * Choose "Github" or "Google" for social login options 4. If you're new, you'll be prompted to create an account. Click on "New here? Create an account" at the bottom of the login screen. 5. Once logged in, you'll be asked to set up your workspace: * Enter a name for your workspace (e.g., your company name) * Provide a short slug (URL-friendly version of your workspace name) 6. Click "Create Workspace" to finalize your setup Great\\! You now have an Oration AI account and workspace ready to go. ## Creating Agents Now that your account is set up, let's create your first AI agent: 1. From your dashboard, navigate to the "Agents" section in the sidebar menu. 2. Click on the "Create Agent" or "Add Agent" button (you may see a "Preview" dropdown with options like "Web Call", "Phone Call", and "Test Agent"). 3. You'll be taken to the Agent Details page. Here's what you need to fill out: * **Name**: Give your agent a name (e.g., "Mary's Dental Clinic") * **System Prompt**: Provide context for your agent. For example: "You are a voice assistant for Mary's Dental, a dental office located at 123 North Face Place, Anaheim, California. The hours are 8 AM to 5PM daily, but they are closed on Sundays." * **Initiation Message**: Set the opening message for your agent (e.g., "Hey, how can I help you?") * **Initiation Type**: Choose how your agent will initiate conversations * **End Call Phrases**: Define phrases that will trigger the end of a conversation * **End Call Message**: Set a closing message for your agent 4. Fill out any additional fields as needed, such as "Configurations", "Advanced Settings", and "Privacy Settings" (visible in the tab menu). 5. Click the "Update" or "Create" button at the bottom of the page to save your agent. Congratulations\\! You've just created your first Oration AI agent. ## Preview Your Agent Before deploying your agent to live interactions, it's a good idea to test it out: 1. Look for a "Preview" button near the top of the Agent Details page. 2. Click on "Preview" and choose the type of interaction you want to test (e.g., "Web Call", "Phone Call", or "Test Agent"). 3. A chat interface will appear, allowing you to interact with your agent. 4. Test various scenarios and conversations to ensure your agent responds correctly. 5. Make any necessary adjustments to your agent's settings based on the preview results. ## Publish Your Agent Once you're satisfied with your agent's performance in the preview, you're ready to publish: 1. Look for a "Publish" or "Go Live" button on the Agent Details page. 2. Review any final settings or confirmations required for publication. 3. Click "Publish" to make your agent available for real interactions. Your Oration AI agent is now live and ready to assist your customers or users\\! *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Voice Agents 101 Source: https://docs.oration.ai/guides/get-started/voice-agents-101 Key concepts that make AI voice interactions feel natural and effective ## The Dynamics of Voice Interaction For a voice agent to be effective, it needs to do more than just "understand" words—it needs to master the rhythm and flow of a natural conversation. High-performance voice agents are designed around several key principles that ensure the experience feels human-like and friction-free. ## Key Conversational Principles The following concepts define how an AI voice agent manages the complexities of real-time dialogue: ### STT (Speech-to-Text) This is how the agent "listens." It converts your spoken words into text in real-time, allowing the system to understand what you're saying as you say it. ### LLM (Large Language Model) This is the "brain" of the conversation. It processes the text to understand your intent, remembers the context of the call, and generates a helpful, human-like response. ### TTS (Text-to-Speech) This is how the agent "speaks." It takes the generated response and turns it back into a natural-sounding voice so you can hear the answer. ### Latency Latency is the "speed of thought" in a conversation. It refers to the time it takes for the agent to process what you've said and begin responding. Low latency is critical; even a one-second delay can make a conversation feel disjointed or robotic. ### Turn-taking Turn-taking is the art of knowing when it's your turn to speak. The agent uses sophisticated detection to understand when you've finished a thought versus when you're just pausing for breath. This prevents awkward silences or the agent accidentally cutting you off. ### Interruption Interruption handling is how the agent reacts when interrupted. A good agent will gracefully stop speaking the moment it detects you've started, quickly pivot its internal "thought process" to listen to your new input, and then respond accordingly. ### Warm Transfer A warm transfer is a seamless hand-off from the AI agent to a human team member, providing the recipient with a summary and context of the conversation before the call is connected. ### Cold Transfer A cold transfer occurs when the AI agent redirects the call to a human representative without providing a prior introduction or context to the recipient. ## Oration AI Features Overview Beyond the core principles of dialogue, Oration AI provides tools to refine and measure the quality of every interaction: * **Evals**: Simulate calls to test agent behavior before deploying agents in production. * **Post-Call Analysis**: Extract insights from call transcripts automatically. * **Scorecards**: Rate agent calls using customizable assessment criteria. * **Terms**: Maintain a library of important business-specific vocabulary to guide agent responses. * **Assists**: Let the agent ask a human colleague for help without transferring the call. These tools help teams monitor quality, maintain consistency, and continuously improve the natural rhythm of their voice agents. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # LeadSquared CRM Source: https://docs.oration.ai/guides/integrations/leadsquared-crm Sync customer data between LeadSquared CRM and Oration AI with automatic webhook-based updates and post-call activity tracking ## Overview The LeadSquared CRM integration enables real-time synchronization between your LeadSquared leads and Oration AI customers. Through webhook-based updates and custom activity tracking, this integration ensures your CRM stays current with every customer interaction and conversation outcome. ## What it does ### Automatic customer synchronization When you create or update a lead in LeadSquared CRM, the integration automatically syncs that information to Oration AI as a customer. This happens through webhooks that are registered on your LeadSquared platform during the connection setup. **How it works:** Once the integration is connected, these operations happen automatically: * **Create**: New leads in LeadSquared CRM automatically become customers in Oration * **Update**: Changes to lead details in LeadSquared CRM sync to Oration in real-time Unlike some integrations, LeadSquared does not support automatic customer deletion through webhooks. Customers must be managed separately in Oration if needed. ### Post-call activity tracking After every conversation with a customer who originated from LeadSquared CRM, Oration automatically creates a custom activity on the lead in LeadSquared. The activity type depends on whether the call was inbound or outbound. This feature requires post-call analysis to be enabled on your agent. **Custom activity types:** During connection setup, Oration creates two custom activity types in your LeadSquared account: * **Oration AI Inbound**: Posted when a customer initiates an inbound call * **Oration AI Outbound**: Posted when your agent makes an outbound call **What's included in activities:** * Conversation summary * Key topics discussed * Custom analysis fields (if configured) Post-call activities are only created for customers that were originally synced from LeadSquared CRM to Oration. ## Getting your LeadSquared credentials To connect LeadSquared CRM with Oration, you need three pieces of information: 1. **Access Key**: Your LeadSquared API access key 2. **Secret Key**: Your LeadSquared API secret key 3. **Host URL**: Your LeadSquared API host URL ### Finding your access key and secret key 1. Log in to your LeadSquared account 2. Navigate to **My Account** > **Settings** > **API and Webhooks** 3. Copy your **Access Key** and **Secret Key** 4. Save these keys securely—you'll need them for the Oration setup Keep your access key and secret key secure. Anyone with access to these credentials can read and modify data in your LeadSquared account. ### Finding your host URL Your host URL is the API endpoint for your LeadSquared instance. You can find the correct host URL for your account in the [LeadSquared API documentation](https://apidocs.leadsquared.com/api-host/). Common host URLs include: * `https://api-in21.leadsquared.com` (India) * `https://api-us11.leadsquared.com` (US) * `https://api-eu1.leadsquared.com` (Europe) Make sure to use the correct host URL for your region. Using the wrong host URL will cause connection failures. ## Connecting LeadSquared CRM to Oration Follow these steps to establish the connection: ### 1. Navigate to workspace settings In your Oration dashboard, click on **Workspace Settings** in the left navigation menu. ### 2. Open integrations Select **Integrations (Beta)** from the settings menu. ### 3. Add LeadSquared CRM connection 1. Find **LeadSquared CRM** in the list of available integrations 2. Click **Add New Connection** 3. Enter the following information: * **Connection Name**: A friendly name to identify this connection (e.g., "Production LeadSquared") * **Access Key**: Paste the access key you copied from LeadSquared * **Secret Key**: Paste the secret key you copied from LeadSquared * **Host URL**: Enter your LeadSquared API host URL ### 4. Test the connection Click **Test Connection** to verify your credentials are valid. Oration will attempt to connect to your LeadSquared instance and confirm the credentials work correctly. If the test fails, double-check: * Your access key and secret key are copied correctly (no extra spaces) * Your host URL is formatted correctly and matches your region * Your API credentials have the necessary permissions in LeadSquared ### 5. Complete the connection Once the connection test succeeds, click **Connect** to finalize the integration. Oration will: 1. **Register webhooks**: Create two webhooks in your LeadSquared platform for lead creation and update events 2. **Create custom activity types**: Set up "Oration AI Inbound" and "Oration AI Outbound" custom activity types in your LeadSquared account 3. **Start monitoring**: Begin listening for webhook events to sync lead changes in real-time Unlike Twenty CRM, LeadSquared integration does not perform an initial sync of existing leads. Only new leads created or updated after the connection is established will be synced to Oration. ## Troubleshooting ### Connection test fails **Check your credentials** Ensure the access key and secret key are copied exactly as shown in LeadSquared, with no extra spaces or characters. **Verify host URL** Confirm you're using the correct host URL for your region. Refer to the [LeadSquared API host documentation](https://apidocs.leadsquared.com/api-host/) to verify. **Confirm API permissions** Make sure your API credentials have permissions to create webhooks and custom activities in LeadSquared. ### Leads not syncing **Check webhook status** Navigate to LeadSquared's webhook settings and verify that the Oration webhooks are active and configured correctly. **Review connection status** In Oration's Integrations page, check that your LeadSquared connection shows as "Active" or "Connected." **Verify lead creation/update** Remember that only leads created or updated after the connection was established will sync to Oration. ### Post-call activities not appearing **Enable post-call analysis on your agent** Verify that post-call analysis is enabled on the specific agent handling the conversations. **Confirm customer source** Post-call activities are only created for customers that originated from LeadSquared CRM. Check that the customer record shows LeadSquared as the source. **Check custom activity types** Verify that "Oration AI Inbound" and "Oration AI Outbound" custom activity types exist in your LeadSquared account. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Twenty CRM Source: https://docs.oration.ai/guides/integrations/twenty-crm Seamlessly sync customer data between Twenty CRM and Oration AI with automatic bidirectional updates and post-call analysis ## Overview The Twenty CRM integration enables seamless synchronization between your Twenty CRM contacts and Oration AI customers. This integration provides bidirectional data flow and automatic post-call analysis updates, ensuring your CRM stays current with every customer interaction. ## What it does ### Automatic customer synchronization When you create, update, or delete a person in Twenty CRM's People object, the integration automatically syncs that information to Oration AI as a customer. This happens through webhooks that Twenty CRM sends to Oration, which we configure using your API credentials. **How it works:** Once the integration is connected, these operations happen automatically: * **Create**: New contacts in Twenty CRM automatically become customers in Oration * **Update**: Changes to contact details in Twenty CRM sync to Oration in real-time * **Delete**: Removing a contact from Twenty CRM removes the associated customer from Oration ### Post-call analysis notes After every conversation with a customer who originated from Twenty CRM, Oration automatically creates a note in Twenty CRM with the post-call analysis data. This feature requires post-call analysis to be enabled on your agent. **What's included in notes:** * Conversation summary * Key topics discussed * Custom analysis fields (if configured) Post-call analysis notes are only created for customers that were originally synced from Twenty CRM to Oration. ## Getting your Twenty CRM credentials To connect Twenty CRM with Oration, you need two pieces of information: 1. **API Key**: Your Twenty CRM API authentication token 2. **Host URL**: Your Twenty CRM instance URL ### Finding your API key 1. Log in to your Twenty CRM account 2. Navigate to **Settings** in the left sidebar 3. Click on **API & Webhooks** section 4. Generate a new API key or copy your existing key 5. Save this key securely—you'll need it for the Oration setup Twenty CRM API & Webhooks Settings Keep your API key secure. Anyone with access to your API key can read and modify data in your Twenty CRM account. ### Finding your host URL 1. In the **API & Webhooks** settings page, click the **Launch** button 2. This opens a new page displaying all API endpoints 3. Look for the **API Host URL** mentioned on this page 4. Copy the complete URL (e.g., `https://your-workspace.twenty.com`) Twenty CRM API Host URL If you're self-hosting Twenty CRM, your host URL will be your custom domain (e.g., `https://crm.yourcompany.com`). ## Connecting Twenty CRM to Oration Follow these steps to establish the connection: ### 1. Navigate to workspace settings In your Oration dashboard, click on **Workspace Settings** in the left navigation menu. ### 2. Open integrations Select **Integrations (Beta)** from the settings menu. ### 3. Add Twenty CRM connection 1. Find **Twenty CRM** in the list of available integrations 2. Click **Add New Connection** 3. Enter the following information: * **Connection Name**: A friendly name to identify this connection (e.g., "Production CRM") * **API Key**: Paste the API key you copied from Twenty CRM * **Host URL**: Enter your Twenty CRM instance URL ### 4. Test the connection Click **Test Connection** to verify your credentials are valid. Oration will attempt to connect to your Twenty CRM instance and confirm the API key works correctly. If the test fails, double-check: * Your API key is copied correctly (no extra spaces) * Your host URL is formatted correctly (includes `https://`) * Your API key has the necessary permissions in Twenty CRM ### 5. Complete the connection Once the connection test succeeds, click **Connect** to finalize the integration. Oration will: 1. **Perform an initial sync**: Import all existing people from your Twenty CRM account into Oration's customer table 2. **Configure webhooks**: Set up webhook listeners in your Twenty CRM instance 3. **Monitor for changes**: Listen for webhook events to sync any future create, update, or delete operations in real-time The initial sync may take a few minutes depending on the number of contacts in your Twenty CRM account. After the initial sync completes, all subsequent changes are synced automatically via webhooks. ## Troubleshooting ### Connection test fails **Check your API key** Ensure the API key is copied exactly as shown in Twenty CRM, with no extra spaces or characters. **Verify host URL format** The host URL should include `https://` and match exactly what appears in your browser when accessing Twenty CRM. **Confirm API permissions** Make sure your API key has read and write permissions for the People object in Twenty CRM. ### Contacts not syncing **Check webhook configuration** Navigate to Twenty CRM's webhook settings and verify that webhooks are configured to send to Oration's endpoint. **Review connection status** In Oration's Integrations page, check that your Twenty CRM connection shows as "Active" or "Connected." ### Post-call analysis notes not appearing **Enable post-call analysis on your agent** Verify that post-call analysis is enabled on the specific agent handling the conversations. **Confirm customer source** Post-call analysis notes are only created for customers that originated from Twenty CRM. Check that the customer record shows Twenty CRM as the source. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Custom Telephony Source: https://docs.oration.ai/guides/phone-numbers/custom-telephony A step by step guide to integrate custom telephony providers using SIP trunking ## Overview This guide outlines how to integrate your existing telephony infrastructure with Oration AI agents, regardless of the agent you are using. To do this, we recommend using **SIP trunking**, which allows you to connect your telephony provider to Oration AI over the internet. This involves setting up a SIP trunking connection, configuring your number to point to it, and then importing that number to Oration AI. **Oration AI SIP server URI:** ``` sip:d4x9uouf0s0.sip.livekit.cloud ``` Oration AI partners with Livekit to provide SIP infrastructure (signaling, media transport) globally across multiple clouds. As a result, there is no single static IP address for the SIP server. ## Elastic SIP Trunking Oration AI recommends using elastic SIP trunking, which is a service offered by cloud communications platforms that enables organizations to connect their existing PBX (Private Branch Exchange) or VoIP (Voice over IP) infrastructure to the Public Switched Telephone Network (PSTN) over the internet using the SIP (Session Initiation Protocol). This method allows you to connect your telephony provider to Oration AI, so your agents can make and receive calls. When using this method, all the telephony functionalities that are supported by Oration AI numbers will also be supported here, assuming that your telephony provider supports it. SIP trunking is a popular service offered by many telephony providers, so most likely your telephony provider would be able to support this. ### Outbound calls You would need to provide the termination SIP URI and Auth Username and Password to Oration AI. You can request this from your telephony provider. Currently, we do not support IP whitelisting for outbound calls. ### Inbound calls You would need to request your telephony provider to add the Oration AI SIP server URI to their setup. The Oration AI SIP server URI is `sip:d4x9uouf0s0.sip.livekit.cloud`. This wil ensure that whenever someone makes a call to your number, it will be forwarded to Oration AI. You can also request your telephony provider to provide the IP addresses or the CIDR IP Range for their server they would be using to send the SIP requests to Oration AI. ### Supported Telephony Providers Here are detailed guides for some popular telephony providers: * [Twilio](/guides/phone-numbers/twilio-integration) ## Troubleshooting **Will it throw errors if the details or configuration is incorrect?** No, Oration AI won't throw errors. However, the setup won't work until a call is made. **My inbound call is not connecting, what should I do?** Please check your origination setting in your SIP trunking provider, as well as the logs in your telephony provider. It might be helpful to open a ticket with them. **My outbound call is not connecting, what should I do?** Please check your termination setting in your SIP trunking provider, and make sure you provide the right termination url to Oration AI and your Auth Username and Password are correct. Also check the logs in your telephony provider, and perhaps open a ticket with them. **How can I change the configuration of the imported number?** Right now you'd need to delete and re-import the number. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Phone Number Management Source: https://docs.oration.ai/guides/phone-numbers/phone-number-management How to set up phone numbers for voice calls ## Setting Up a Phone Number You can add a new phone number directly from the Oration AI dashboard. Here’s how to use the **New phone number** form: Create Phone Number ### Field Explanations * **Name**\ Give your phone number a human-readable name (e.g., "Support Line", "Sales Inbound"). * **Phone Number**\ Enter the phone number you want to add. This is the number your customers will call or receive calls from. * **Outbound Termination Uri**\ The address of your SIP trunk. This is required for SIP-based phone numbers. * **Outbound Trunk Username**\ The username for authenticating with your SIP trunk provider. * **Outbound Trunk Password**\ The password for your SIP trunk account. * **Inbound Allowed IP Range**\ The IP range of your SIP provider to whitelist. This is required for inbound calls received on your SIP-based phone numbers. After filling in all required fields, click **Create Phone Number** to add the number to your Oration AI account. In case you need help in getting these details, you can refer to our [Custom Telephony Provider](/guides/phone-numbers/custom) guide. In case you need want to import your Twilio phone number, you can refer to our [Twilio](/guides/phone-numbers/twilio) guide. *** ## Next Steps Once your phone number is set up, you should be able to see it in the dashboard. Phone Number List Click on that phone number to assign it to an agent for inbound or outbound calls. Phone Number Detail *** ## Best Practices * Use descriptive names for each phone number to keep your setup organized. * Double-check SIP credentials and URLs for accuracy to avoid connection issues. * Make sure you don't use duplicate phone numbers. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Twilio Integration Source: https://docs.oration.ai/guides/phone-numbers/twilio-integration A step by step guide to connect to your Twilio account via SIP trunking ## Steps to Create Elastic SIP Trunking in Twilio ### 1. Create the trunk, give it a name, and toggle some general settings * Search and find the "Elastic SIP Trunking" in the console. Click on the "Create Trunk" button. Remember to keep saving the changes after each step. Twilio Trunk Creation ### 2. Setup termination (this is for outbound) The termination SIP URI here is important, we would use it in later steps. For your elastic SIP trunk to accept our outbound request, you need to whitelist IP address or create a auth with username and password. * Click on Termination in the left sidebar. Twilio Termination Setup For authenticating, we recommend using a username and password. * Click on the Plus button to create a new Credentials List. Twilio Credentials List * You can create a new Credentials List. Twilio Credentials List Form If you opt for the auth route, you need to specify the username and password in the next step when importing the number to Oration AI. Currently Oration AI SIP server does not have a static IP, so if you opt for the IP route, you need to whitelist all the IP addresses in the range. `0.0.0.0/1` and `128.0.0.0/1` ### 3. Setup origination (this is for inbound) * Here you will specify Oration AI's SIP server address as the origination SIP URI: ``` sip:d4x9uouf0s0.sip.livekit.cloud ``` Twilio Origination Setup You should be able to see the origination URI in the console. Twilio Origination SIP URI List ### 4. Move numbers to Elastic SIP Trunking You've created the elastic SIP trunk, now you would need to purchase numbers / move existing numbers to this trunk. Now the number is set up with your elastic SIP trunking, you need to import the number to Oration AI so that we will know how to route the call. Click on the add number button in the top left of the dashboard. Add Number Once number import is complete, your number will show up in the list of numbers. Number Addition Complete ### 5. Import numbers to Oration AI Now the number is imported, make note of three things: 1. The termination SIP URI you set up in Step 1. It usually ends with `.pstn.twilio.com`. 2. The username and password you set up in Step 1. 3. The IP range of your SIP provider (twilio) to whitelist. This is required for inbound calls received on your SIP-based phone numbers. We have gone through [Twilio's documentation](https://www.twilio.com/docs/sip-trunking/ip-addresses) to get the list of IP ranges. There are as follows: * 54.172.60.0/30 * 54.244.51.0/30 * 54.171.127.192/30 * 35.156.191.128/30 * 54.65.63.192/30 * 54.169.127.128/30 * 54.252.254.64/30 * 177.71.206.192/30 * 168.86.128.0/18 You can now follow the steps in the [Phone Numbers](/guides/phone-numbers/introduction) guide to import the number to Oration AI. *** ## Troubleshooting ### 1. After connecting, inbound works but outbound does not work? **Check the termination SIP URI** Make sure there is no space in it and that it ends with `.pstn.twilio.com`. **Check the user name and credentials** Please ensure you entered the correct user name and credentials which are shown in this dialog. Please note that the user name is different from the friendly name that appears in the credential list. Double check if you happen to give a different name. Twilio Credentials List Form ### 2. How do I set up dialing to international countries? **Search and find the "Voice Geographic Permissions" setting in Twilio.** Twilio Geo Permissions **Choose "Elastic Sip Trunking" in selector, and select the countries you would like to dial.** Twilio Elastic SIP Selector *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Evaluations (Evals) Source: https://docs.oration.ai/guides/quality-assurance/evals Test and validate your AI agents before deploying to production using evaluation suites in Oration AI ## Overview **Evaluations** (Evals) in Oration AI provide a powerful testing environment that lets you validate how your AI agents handle different scenarios before deploying them to real customers. With Evals, you can catch issues early and ensure your AI agents deliver consistent, accurate responses across every customer interaction. *** ## 1. Creating Evaluation Suites Evaluation Suites help you organize your tests into comprehensive collections that cover all critical aspects of your AI agent's performance. To create a new evaluation suite: 1. Navigate to **Evaluation Suites** in the left sidebar. 2. Click the **Create Suite** button in the top right corner. 3. Give your suite a descriptive name (e.g., "Customer Support Flow Tests" or "Booking Agent Validation"). 4. Add a description explaining what scenarios this suite covers. 5. Select the agent you want to test. Once created, you can add individual evaluations to your suite to test different aspects of your agent's behavior. *** ## 2. Next Reply Evaluations **Next Reply** evaluations test individual responses to verify your agent provides appropriate answers in specific conversation contexts. **When to use:** Use Next Reply evaluations when you want to test how your agent responds to a single message or specific user input. **How to create:** 1. Open your evaluation suite and click **Add Evaluation**. 2. Select **Next Reply** as the evaluation type. 3. **Name your test:** Give it a clear, descriptive name (e.g., "Greeting Response Test"). 4. **Set conversation context:** On the right side, under 'Chat Messages', provide any previous messages that set up the scenario. 5. **Define success criteria:** Describe what makes a response acceptable. Be specific about required information, tone, or actions. **Example:** * **User Message:** "I am busy right now" * **Success Criteria:** Agent should respond with a polite message that they will call back later. Agent should not ask any further questions * **Success Example:** "No problem, I'll call back later." *** ## 3. Tool Invocation Evaluations **Tool Invocation** evaluations ensure your agent calls the right tools at the right times during customer interactions. **When to use:** Use Tool Invocation tests when your agent needs to trigger specific functions, APIs, or integrations based on user requests. **How to create:** 1. In your evaluation suite, click **Add Evaluation**. 2. Select **Tool Invocation** as the evaluation type. 3. **Name your test:** Provide a descriptive name (e.g., "Order Lookup Tool Test"). 4. **Set conversation context:** Add any previous conversation history needed for both User and Agent. 5. **Specify expected tool:** Select which tool should be invoked. **Example:** * **Context:** Agent has asked for order number * **User Message:** "My order number is 12345" * **Expected Tool:** `lookup_order` * **Success Criteria:** Agent should invoke the lookup\_order tool with the correct order ID extracted from the user's message. *** ## 4. Conversation Evaluations **Conversation** evaluations simulate complete multi-turn interactions from start to finish, following defined scripts to test your agent's ability to handle realistic customer journeys. **When to use:** Use Conversation evaluations for end-to-end testing of complete customer scenarios, including multiple exchanges, tool calls, and resolution flows. **How to create:** 1. In your evaluation suite, click **Add Evaluation**. 2. Select **Conversation** as the evaluation type. 3. **Name your test:** Provide a descriptive name (e.g., "Complete Booking Flow"). 4. **Build conversation script:** Add multiple turns of conversation: * User messages * Expected agent responses or behaviors * Decision points and branches 5. **Define a conversation script:** Write out the instructions and context the evaluating agent should follow to interact with your AI agent during the simulated conversation. The script should include the dialogue prompts, expected actions, and any guidelines about how the evaluating agent should behave or respond, ensuring realistic and relevant exchanges throughout the evaluation. 6. **Define success criteria:** Describe what a successful conversation looks like: * All required information collected * Customer issue resolved * Professional tone maintained 7. **Maximum conversation steps:** Set how many turns your evaluation agent should have with your AI agent. **Example:** * **Conversation script:** You recently ordered a book from Acme Inc, but the delivery is delayed—it was supposed to arrive yesterday. Start a conversation with the AI agent to find out the new delivery date. Explain that you don't have your order ID available, but your registered phone number is 202-555-0123. Be polite but persistent in seeking an update. * **Success Criteria:** The agent should apologize for the delay, ask for the order id. If order ID is not known, it should ask for registered phone number and respond with the new estimated delivery date. *** ## 5. Running Evaluations Once you've created your evaluations, you can run them individually or execute an entire suite: * **Run single evaluation:** Click the play button next to any evaluation to test it individually. * **Run entire suite:** Click **Run Suite** to execute all evaluations sequentially and get a comprehensive report. Each run generates detailed results showing: * Pass/Fail status * Agent's actual responses * Expected vs. actual behavior * Tool invocations made * Success criteria met or missed *** ## 6. Analyzing Results Evaluation Results After running evaluations, review the results to identify issues and areas for improvement: * **Overall Pass Rate:** See what percentage of evaluations passed. * **Individual Test Results:** Drill down into each evaluation to see: * Full conversation transcript * Tool invocations (expected and actual) * Why tests passed or failed * **Agent Responses:** Review exact agent outputs to understand behavior. Use these insights to refine your agent's prompts, add training examples, adjust tool configurations, or update conversation logic. *** ## Best Practices * **Test before deploying:** Always run evaluations after making changes to your agent's configuration before pushing to production. * **Cover edge cases:** Don't just test happy paths—include difficult scenarios, unclear inputs, and error conditions. * **Maintain a comprehensive suite:** Build evaluation suites that cover all critical customer journeys and use cases. * **Update tests regularly:** As you add new features or modify agent behavior, update your evaluation suites accordingly. * **Use specific success criteria:** Clear, measurable criteria make it easier to identify when tests fail and why. * **Combine evaluation types:** Use Next Reply for quick validations, Tool Invocation for integration testing, and Conversation for end-to-end flows. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Scorecards Source: https://docs.oration.ai/guides/quality-assurance/scorecards How to implement automated quality assurance for your AI agents using scorecards in Oration AI ## Overview **Scorecards** in Oration AI are automated quality assessments that score each conversation based on criteria you define. Instead of manually reviewing calls for quality, the AI evaluates them for you—checking if your agent followed guidelines, stayed on-brand, and met your service standards. *** ## 1. Creating a Scorecard Create Scorecard To create a new scorecard, navigate to **Scorecards** in the left sidebar and click the **Create Scorecard** button in the top right corner. You'll need to configure the following fields: * **Name:** Give your scorecard a descriptive name (e.g., "Customer Support Quality Standards"). * **Description:** Explain what this scorecard evaluates (e.g., "Evaluates agent performance on customer service quality, brand compliance, and issue resolution"). * **Scorecard Prompt:** Provide instructions to guide the AI on how to evaluate conversations. This tells the system what to look for and how to assess quality. * **Passing Points:** Set the minimum score required to pass the evaluation. For example, if your total scorecard is worth 100 points, you might set passing at 80. **Example Scorecard Prompt:** "You are an expert QA agent and your job is to evaluate the conversation between a user and AI agent on the basis of certain pre-defined evaluation criteria. If in any situation, a certain criteria is not applicable, assign full score to the criteria." *** ## 2. Adding Evaluation Questions Add Questions After setting up your scorecard basics, you'll need to add specific questions that will be evaluated. Click **Add Question** to get started. For each question, configure: * **Question:** The specific criteria being evaluated (e.g., "Did the agent greet the customer professionally and introduce themselves?"). * **Description:** Provide detailed guidance on what to look for (e.g., "Agent should say hello, state their name, and offer assistance"). * **Max Points:** Assign the maximum points this question is worth (e.g., 10 points). * **Evaluation Type:** Choose between: * **Score:** For questions requiring a numerical rating * **Pass/Fail:** For yes-or-no criteria * **Fatal Question:** Toggle this on if failing this specific question should automatically fail the entire scorecard, regardless of other scores. This is perfect for critical requirements like compliance or safety issues. You can add as many questions as needed. Ensure your max points add up to create a meaningful total score that aligns with your passing points threshold. *** ## 3. Attaching Scorecards to Agents Once your scorecard is ready, you need to attach it to one or more agents: 1. Navigate to your agent's page from the **Agents** section. 2. Click on the **Quality Assurance** tab. 3. Click **Add Scorecard** and select the scorecard you created. 4. Specify the **percentage of conversations** where you want QA to be applied (e.g., 100% for all conversations, or 20% for a sample-based approach). Your agent will now be automatically evaluated based on the scorecard criteria you defined. *** ## 4. Reviewing Scorecard Results Scorecard Results To view scorecard evaluations for your conversations, go back to **Scorecards** in the left navigation. Here you'll see: * **Total Score:** The overall score achieved out of the maximum possible points. * **Pass/Fail Status:** Whether the conversation met the passing threshold. * **Question-by-Question Breakdown:** Individual scores and evaluations for each question in your scorecard. * **AI Reasoning:** Explanations for why certain scores were assigned. This structured feedback helps you identify patterns, coach your agents, and continuously improve service quality. *** ## Best Practices * **Define clear, measurable criteria** in your scorecard questions to ensure consistent evaluations. * **Use Fatal Questions sparingly** for only the most critical compliance or safety requirements. * **Start with key metrics** that matter most to your business (greeting quality, issue resolution, brand compliance). * **Regularly review scorecard results** to identify training opportunities and areas for improvement. * **Update scorecards** as your business needs and quality standards evolve. * **Balance automated QA** with periodic manual reviews to ensure the AI is evaluating correctly. * **Consider sampling** (e.g., 20% of conversations) if you have high call volumes, then increase to 100% for critical agents. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Widget SDK Source: https://docs.oration.ai/guides/widgets/widget-sdk Embeddable conversation widget for Oration AI agents ## Overview The Oration Widget SDK is a lightweight, embeddable web component (``) that adds AI voice and chat agents to any website. No framework or build step required — just a script tag. ## Quick start ```html theme={null} ``` Widget initial view - Ready to talk button Widget initial view - Ready to talk button ## Getting your keys 1. **Public key** — copy your workspace public key from the [Oration Dashboard](https://www.oration.ai/app) 2. **Agent ID** — create an agent and copy its ID from the agents section ## Configuration ### Required attributes | Attribute | Type | Description | | ------------------ | ------ | ------------------------------------- | | `public-key` | string | Your Oration workspace public key | | `default-agent-id` | string | The agent ID to use for conversations | ### Optional attributes | Attribute | Type | Default | Description | | -------------------------- | ----------- | ------------------------------------------- | --------------------------------------------------------------------- | | `conversation-type` | string | `"web"` | `"web"`, `"chat"`, or `"both"` | | `agent-language-id-map` | JSON string | — | Map of BCP-47 language codes to agent IDs | | `size` | string | `"full"` | `"full"` (380px) or `"tiny"` (260px) | | `position` | string | `"bottom-right"` | `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"` | | `color-mode` | string | `"system"` | `"light"`, `"dark"`, or `"system"` | | `theme` | JSON string | — | Custom theme colors (see [Theme customization](#theme-customization)) | | `dynamic-variables` | JSON string | — | `Record` passed as session context to the agent | | `logo` | string | — | URL of a custom logo to replace the default | | `animate-logo` | boolean | `true` for default logo, `false` for custom | Control logo spin animation | | `main-label` | string | — | Override the initial "Ready to start" label | | `orb-color` | string | — | Hex color for the AI orb (e.g. `"#2563eb"`) | | `require-terms-acceptance` | boolean | `false` | Show a terms acceptance gate before the first conversation | | `terms-text` | string | — | Custom terms text (used when `require-terms-acceptance` is enabled) | | `enable-dtmf` | boolean | `false` | Show a DTMF numpad during voice calls | ## Conversation types ### Web mode (default) Real-time voice conversation. ```html theme={null} ``` Widget in voice conversation mode with live transcript Widget in voice conversation mode with live transcript ### Chat mode Text-based chat interface. ```html theme={null} ``` Widget in chat mode with text conversation Widget in chat mode with text conversation ### User choice mode Lets users pick between voice and chat. ```html theme={null} ``` Widget conversation type selector - Voice or Chat options Widget conversation type selector - Voice or Chat options ## Widget sizes | Value | Width | Use case | | ------------------ | ----- | ---------------------------- | | `"full"` (default) | 380px | Standard widget with full UI | | `"tiny"` | 260px | Compact, minimal footprint | Tiny widget size during voice conversation Tiny widget size during voice conversation ## Multi-language support Map BCP-47 language codes to specific agent IDs. A language selector will appear in the widget when the map contains at least one entry. ```html theme={null} ``` Widget with language selector dropdown showing English and Hindi options Widget with language selector dropdown showing English and Hindi options **Agent selection logic:** * If `agent-language-id-map` is provided, the map takes priority over `default-agent-id` * If `default-agent-id` exists as a value in the map, it is pre-selected * Otherwise the first entry in the map is used as the default ## Dynamic variables Pass context to your agent using the `dynamic-variables` attribute. Values must be a JSON object of string key-value pairs. ```html theme={null} ``` Variables are available in session metadata during the conversation. Common uses: user identification, current page context, subscription tier, A/B test variant. ### Programmatic updates ```javascript theme={null} const widget = document.querySelector('oration-widget'); widget.setAttribute('dynamic-variables', JSON.stringify({ userId: "67890", plan: "enterprise", currentPage: "/checkout" })); ``` ## Theme customization Pass a JSON object to `theme` with any subset of the following keys. Missing keys fall back to defaults. ### Theme keys | Key | Role | | ---------------- | ------------------------------------ | | `base` | Primary background | | `base_hover` | Hover state background | | `base_active` | Active/pressed state background | | `base_border` | Border color | | `base_subtle` | Secondary / muted text | | `base_primary` | Primary text | | `base_error` | Error states | | `accent` | Primary accent (buttons, highlights) | | `accent_hover` | Accent hover | | `accent_active` | Accent active/pressed | | `accent_border` | Accent border | | `accent_subtle` | Muted accent elements | | `accent_primary` | Text on accent backgrounds | All values must be hex color strings. ```html theme={null} ``` ```html theme={null} ``` Widget with custom orange theme applied to chat interface Widget with custom orange theme applied to chat interface ### Color mode Use `color-mode` to force light or dark theme, or let the widget follow the user's system preference: ```html theme={null} ``` ## External button trigger Any element with `id="oration-conversation-trigger"` will open the widget when clicked. The trigger respects the widget's current state (no-op while connecting). ```html theme={null} ``` If `conversation-type="both"`, the trigger shows the conversation type selector first. ## Terms acceptance Show a consent gate before the first conversation. Acceptance is stored in `localStorage` and won't be shown again. ```html theme={null} ``` ## Troubleshooting **Widget not loading** — check the browser console, verify the script tag is present, and confirm your public key and agent ID are correct. **Styling issues** — the widget uses Shadow DOM for style isolation. Custom styles must go through the `theme` attribute. **No microphone access** — browser microphone permissions must be granted for voice conversations. **Conversation fails** — verify the agent is configured and your workspace has sufficient credits. Your public key is visible in client-side code. Only use it on authorized domains. Never expose private API keys in the browser. *** > Need help? Contact us at [support@oration.ai](mailto:support@oration.ai) # Managing Members Source: https://docs.oration.ai/guides/workspace-settings/adding-new-users Invite, manage, and organize members in your Oration AI workspace ## Members Overview The **Members** page allows you to manage all users in your workspace. You can invite new members, view existing ones, handle pending requests, and assign roles. *** ## How to Add New Members You can add new members to your workspace in two ways: ### 1. Share an Invite Link 1. At the top of the Members page, locate the **Invite Link** section. 2. Click the **eye icon** to reveal the full invite link if it's hidden. 3. Click the **copy icon** to copy the link to your clipboard. 4. Share this link with anyone you'd like to join your workspace. * When they open the link, they'll be prompted to join your workspace as a member. ### 2. Invite People Directly 1. Click the **Invite People** button in the top right of the Manage Members section. 2. Enter the email addresses of the people you want to invite. 3. Assign a role (e.g., Owner, Member) for each invitee if prompted. 4. Send the invitation. * Invited users will receive an email with instructions to join your workspace. *** ## Managing Members ### Viewing Members * Use the **All**, **Members**, and **Pending** tabs to filter the member list. * Use the **search** and **filter** options to find specific members. ### Pending Members Pending invitations and join requests appear under the **Pending** tab. You can: * **Approve** a request to add the person as a member. * **Decline** a request to reject the join request. ### Changing Member Roles 1. Find the member whose role you want to change. 2. Click the menu icon next to their name. 3. Select a new role from the available options. ### Removing a Member 1. Find the member you want to remove. 2. Click the menu icon next to their name. 3. Select **Remove from Workspace**. > Removing a member will revoke their access to the workspace immediately. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Audit Logs Source: https://docs.oration.ai/guides/workspace-settings/audit-logs Track and review all activities in your Oration AI workspace ## What are Audit Logs? **Audit Logs** keep a detailed record of all activities and changes made within your workspace. They help you monitor who did what, when, and to which resource—ensuring transparency, accountability, and security. Terms ### What you can see in Audit Logs * **User:** Who performed the action. * **Actor Type:** The type of actor (e.g., user, system). * **Resource:** What was affected (e.g., agent, agent settings). * **Action:** What was done (e.g., created, updated). * **Event Name & Description:** Details about the event, including what changed and any relevant context. * **Timestamp:** (Not shown in the image, but typically included) When the action occurred. ### Why use Audit Logs? * **Security:** Track all changes for compliance and investigation. * **Accountability:** See which user made each change. * **Troubleshooting:** Quickly identify when and how a configuration was modified. You can filter, sort, and search audit logs to find specific events or review recent activity in your workspace. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai) # Managing Teams Source: https://docs.oration.ai/guides/workspace-settings/teams Create and manage teams within your Oration AI workspace to organize members and control access ## What are Teams? **Teams** allow you to organize workspace members into groups for better collaboration and access management. You can create teams, join existing teams, and manage team memberships within your workspace. *** ## My Teams vs Other Teams The Teams page is divided into two sections: ### My Teams Teams you are currently a member of. You can view team members and leave teams you no longer need to be part of. ### Other Teams Teams in your workspace that you are not a member of. You can request to join these teams. *** ## Creating a New Team 1. Navigate to **Settings** → **Workspace** → **Teams**. 2. Click the **Create Team** button in the top right. 3. Enter a name for your team. 4. Click **Create** to save the team. > You will automatically be added as a member of the team you create. *** ## Managing Team Members ### Adding Members to a Team 1. Go to the team you want to manage. 2. Click **Add Members**. 3. Select workspace members to add to the team. ### Removing Members from a Team 1. Go to the team and find the member you want to remove. 2. Click the menu icon next to their name. 3. Select **Remove from Team**. *** ## Joining a Team 1. Navigate to the **Other Teams** section. 2. Find the team you want to join. 3. Click **Join** to request membership. *** ## Leaving a Team 1. Navigate to **My Teams**. 2. Find the team you want to leave. 3. Click the menu icon and select **Leave Team**. *** ## Deleting a Team 1. Navigate to **My Teams**. 2. Find the team you want to delete. 3. Click the menu icon and select **Delete Team**. > Only team owners or workspace admins can delete teams. *** > Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai)