> ## Documentation Index > Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt > Use this file to discover all available pages before exploring further. # Structured Tests > Create dynamic, rule-based evaluators that respond to specific conversation conditions export const CopyPageButton = () => { if (typeof window !== 'undefined') { setTimeout(function () { if (document.getElementById('ck-tools')) return; var anchor = document.getElementById('content-area') || document.querySelector('.mdx-content'); if (!anchor) return; if (!document.getElementById('ck-style')) { var s = document.createElement('style'); s.id = 'ck-style'; s.textContent = '#ck-tools{position:absolute;top:6px;right:0;z-index:100;font-family:inherit;}' + '.ck-row{display:inline-flex;align-items:stretch;border:1px solid rgba(0,0,0,0.15);border-radius:8px;overflow:hidden;background:#fff;}' + ':root.dark .ck-row{background:rgba(255,255,255,0.06);border-color:rgba(255,255,255,0.12);}' + '.ck-btn{padding:5px 12px;border:none;background:none;cursor:pointer;font-size:13px;font-weight:500;font-family:inherit;color:#374151;}' + ':root.dark .ck-btn{color:#d1d5db;}' + '.ck-btn:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-btn:hover{background:rgba(255,255,255,0.06);}' + '.ck-chevron{padding:5px 8px;border:none;background:none;cursor:pointer;font-size:14px;font-family:inherit;color:#374151;}' + ':root.dark .ck-chevron{color:#d1d5db;}' + '.ck-chevron:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-chevron:hover{background:rgba(255,255,255,0.06);}' + '.ck-divider{width:1px;background:rgba(0,0,0,0.12);flex-shrink:0;}' + ':root.dark .ck-divider{background:rgba(255,255,255,0.12);}' + '.ck-dd{position:absolute;top:calc(100% + 4px);right:0;min-width:180px;background:#fff;border:1px solid rgba(0,0,0,0.12);border-radius:8px;box-shadow:0 4px 12px rgba(0,0,0,0.1);padding:4px;display:none;z-index:200;}' + ':root.dark .ck-dd{background:#1f2937;border-color:rgba(255,255,255,0.1);box-shadow:0 4px 16px rgba(0,0,0,0.35);}' + '.ck-item{display:block;width:100%;padding:7px 12px;border:none;background:none;border-radius:6px;cursor:pointer;font-size:13px;font-family:inherit;text-align:left;color:#374151;}' + ':root.dark .ck-item{color:#d1d5db;}' + '.ck-item:hover{background:rgba(0,0,0,0.05);}' + ':root.dark .ck-item:hover{background:rgba(255,255,255,0.07);}'; document.head.appendChild(s); } var wrap = document.createElement('div'); wrap.id = 'ck-tools'; var row = document.createElement('div'); row.className = 'ck-row'; var mainBtn = document.createElement('button'); mainBtn.className = 'ck-btn'; mainBtn.textContent = 'Copy page'; var divider = document.createElement('span'); divider.className = 'ck-divider'; var chevron = document.createElement('button'); chevron.className = 'ck-chevron'; chevron.textContent = '▾'; var dd = document.createElement('div'); dd.className = 'ck-dd'; function closeDD() { dd.style.display = 'none'; } function openDD() { dd.style.display = 'block'; } chevron.onclick = function (e) { e.stopPropagation(); if (dd.style.display === 'block') { closeDD(); } else { openDD(); } }; document.addEventListener('click', function (e) { if (!e.target.closest('#ck-tools')) { closeDD(); } }); document.addEventListener('keydown', function (e) { if (e.key === 'Escape') { closeDD(); } }); function makeItem(label, fn) { var b = document.createElement('button'); b.className = 'ck-item'; b.textContent = label; b.onclick = function () { fn(); closeDD(); }; return b; } function getMarkdown() { var walk = function (node) { if (!node) return ''; if (node.nodeType === 3) return node.textContent || ''; if (node.nodeType !== 1) return ''; var tag = node.tagName.toLowerCase(); var skip = ['script', 'style', 'svg', 'noscript', 'button', 'iframe']; if (skip.indexOf(tag) !== -1) return ''; if (node.id === 'ck-tools') return ''; var ch = Array.from(node.childNodes).map(walk).join(''); if (tag === 'h1') return '\n# ' + ch.trim() + '\n\n'; if (tag === 'h2') return '\n## ' + ch.trim() + '\n\n'; if (tag === 'h3') return '\n### ' + ch.trim() + '\n\n'; if (tag === 'p') return '\n' + ch.trim() + '\n\n'; if (tag === 'pre') return '\n```\n' + node.textContent.trim() + '\n```\n\n'; if (tag === 'li') return '- ' + ch.trim() + '\n'; if (tag === 'code') return '`' + ch.trim() + '`'; return ch; }; var content = document.querySelector('.mdx-content') || document.getElementById('content-area') || document.body; return walk(content).replace(/\n\n\n+/g, '\n\n').trim(); } function copyMd() { var md = getMarkdown(); navigator.clipboard.writeText(md).then(function () { mainBtn.textContent = 'Copied!'; setTimeout(function () { mainBtn.textContent = 'Copy page'; }, 2000); }); } function viewMd() { var md = getMarkdown(); var safe = md.split('&').join('&').split('<').join('<').split('>').join('>'); var html = '' + safe + ''; window.open(URL.createObjectURL(new Blob([html], { type: 'text/html' })), '_blank'); } function openClaude() { var prompt = 'Can you read this Cekura docs page ' + window.location.href + ' so I can ask you questions?'; window.open('https://claude.ai/new?q=' + encodeURIComponent(prompt), '_blank'); } mainBtn.onclick = copyMd; dd.appendChild(makeItem('Copy page', copyMd)); dd.appendChild(makeItem('View as Markdown', viewMd)); dd.appendChild(makeItem('Open in Claude', openClaude)); row.appendChild(mainBtn); row.appendChild(divider); row.appendChild(chevron); wrap.appendChild(row); wrap.appendChild(dd); anchor.style.position = 'relative'; anchor.insertBefore(wrap, anchor.firstChild); }, 50); } return null; }; ## What are Structured Tests? Structured Tests is a specialized evaluator type that allows you to create dynamic, rule-based test scenarios. Unlike traditional evaluators that follow a linear script, Structured Tests evaluators can adapt their behavior based on what the agent says during the conversation. This makes them ideal for testing complex workflows where the conversation can take multiple paths depending on the agent's responses. ## When to Use Structured Tests Use Structured Tests evaluators when you need to: * **Test branching conversations**: Handle different conversation paths based on agent responses * **Simulate decision trees**: Test scenarios where user responses depend on what the agent asks * **Create adaptive evaluators**: Build evaluators that can handle unexpected agent responses * **Test IVR (Interactive Voice Response) flows**: Simulate interactive voice response systems with menu options * **Validate error handling**: Test how agents handle various user inputs and edge cases Testing an appointment booking agent where the flow changes based on whether the agent offers available slots, asks for rescheduling, or cancels the appointment entirely. ## Structure A Structured Tests evaluator consists of two main components: ### 1. Role The `role` defines who the testing agent is pretending to be. ```json theme={null} { "role": "You are a customer calling to cancel an appointment" } ``` Keep the role concise and clear. It sets the context for the entire conversation. ### 2. Conditions The `conditions` array defines the rules and actions for the evaluator. Each condition specifies: * **When** a certain situation occurs (the condition) * **What** the testing agent should do (the action) ```json theme={null} { "role": "You are a customer calling to cancel an appointment", "conditions": [ { "id": 0, "condition": "FIRST_MESSAGE", "action": "Hi, I need to cancel my appointment", "type": "standard", "fixed_message": true }, { "id": 1, "condition": "The agent asks for your name", "action": "Provide your name as John Smith", "type": "standard", "fixed_message": false }, { "id": 2, "condition": "The agent asks for a reason", "action": "Say you have a scheduling conflict", "type": "standard", "fixed_message": false } ] } ``` ## Condition Fields Each condition object has the following fields: Unique identifier for the condition. The first condition must use `id: 0`. Each ID must be unique — duplicate IDs are rejected. The trigger condition that determines when this action should be taken. **Special cases**: * When `id` is 0, the condition must be the string `"FIRST_MESSAGE"` (represents the first message) * When `type` is `action_followup`, the condition should be an integer referencing the previous condition ID * For standard conditions, the condition is a string describing the trigger What the testing agent should say or do when the condition is met. Cannot be empty or whitespace-only. The interpretation depends on the `fixed_message` field: * When `fixed_message` is `false`: Contains instructions for the testing agent to interpret * When `fixed_message` is `true`: Contains the exact message to send word-for-word **Exception**: The `FIRST_MESSAGE` condition (id: 0) may have an empty action when the main agent speaks first. The condition type. Must be explicitly provided — there is no default. Options: * `standard`: Normal condition triggered by the conversation context * `action_followup`: Fires on the **next turn** after the referenced condition — the testing agent sends the referenced condition's message, waits for the main agent to reply, then sends this message Must be explicitly set to `true` or `false` on every condition — omitting it returns a validation error. * `true`: The `action` field contains the exact message to send word-for-word * `false`: The `action` field contains instructions for the testing agent to interpret naturally **Note**: The FIRST\_MESSAGE condition (id: 0) must have `fixed_message: true`. ## Validation Rules The backend enforces the following constraints on all Structured Tests evaluators. Violations return a validation error. The first condition in the `conditions` array must satisfy all three requirements: * `condition` must equal `"FIRST_MESSAGE"` (not empty, not any other string) * `id` must be `0` * `fixed_message` must be `true` ```json theme={null} // ✅ Valid { "id": 0, "condition": "FIRST_MESSAGE", "action": "Hello", "type": "standard", "fixed_message": true } // ❌ Invalid — condition is empty { "id": 0, "condition": "", "action": "Hello", "type": "standard", "fixed_message": true } // ❌ Invalid — fixed_message is missing { "id": 0, "condition": "FIRST_MESSAGE", "action": "Hello", "type": "standard" } ``` The `action` field cannot be empty or whitespace-only. This rule applies to all conditions except FIRST\_MESSAGE (id: 0), which may have an empty action when the main agent speaks first. ```json theme={null} // ✅ Valid — FIRST_MESSAGE may have empty action { "id": 0, "condition": "FIRST_MESSAGE", "action": "", "type": "standard", "fixed_message": true } // ❌ Invalid — non-FIRST_MESSAGE condition has empty action { "id": 1, "condition": "The agent greets you", "action": "", "type": "standard", "fixed_message": false } ``` Every condition must include a `type` field. There is no default — omitting `type` returns a validation error. ```json theme={null} // ✅ Valid { "id": 1, "condition": "Agent asks for name", "action": "Provide name", "type": "standard", "fixed_message": false } // ❌ Invalid — type is missing { "id": 1, "condition": "Agent asks for name", "action": "Provide name", "fixed_message": false } ``` Every condition must include a `fixed_message` field set to `true` or `false`. Omitting it returns a validation error. ```json theme={null} // ✅ Valid { "id": 1, "condition": "Agent asks for name", "action": "Provide name", "type": "standard", "fixed_message": false } // ❌ Invalid — fixed_message is missing { "id": 1, "condition": "Agent asks for name", "action": "Provide name", "type": "standard" } ``` Every condition must have a unique `id`. Duplicate IDs are rejected. ```json theme={null} // ❌ Invalid — id 1 appears twice [ { "id": 0, "condition": "FIRST_MESSAGE", "action": "Hello", "type": "standard", "fixed_message": true }, { "id": 1, "condition": "Agent asks for name", "action": "Provide name", "type": "standard", "fixed_message": false }, { "id": 1, "condition": "Agent asks for email", "action": "Provide email", "type": "standard", "fixed_message": false } ] ``` Structured Tests evaluators require a `scenario_language`. Set it by assigning a personality with a language configured. If you provide a personality, the language is inferred automatically; if no personality is set, `scenario_language` must be explicitly provided. This also applies when changing an existing evaluator's type to Structured Tests. ## First Message (id: 0) The condition with `id: 0` is special—it represents the **first message** the testing agent sends to start the conversation. Three rules apply to this condition: 1. `condition` must be the string `"FIRST_MESSAGE"` 2. `fixed_message` must be `true` 3. `action` may be empty if the main agent speaks first ```json theme={null} { "id": 0, "condition": "FIRST_MESSAGE", "action": "Hi, I need to cancel my appointment", "type": "standard", "fixed_message": true } ``` **When the main agent speaks first**, set `action` to an empty string: ```json theme={null} { "id": 0, "condition": "FIRST_MESSAGE", "action": "", "type": "standard", "fixed_message": true } ``` The `condition` field for the first message must be `"FIRST_MESSAGE"` exactly. An empty string or any other value will fail validation. ## Condition Types ### Standard Conditions Standard conditions are evaluated based on the conversation context. They trigger when the specified condition is met. ```json theme={null} { "id": 1, "type": "standard", "condition": "The agent asks for your account number", "action": "Provide your account number", "fixed_message": false } ``` ### Action Followup Conditions An `action_followup` fires on the **next turn** after the condition it references. It does not fire immediately. The sequence is: 1. Testing agent sends the message from condition X 2. Main agent receives it and replies 3. `action_followup` (with `condition: X`) fires — testing agent sends this message The main agent's reply is received but does not affect whether the followup fires. Because of this, `action_followup` has two key uses: * **Multi-part responses**: send several messages across consecutive turns after a single trigger * **Scripted sequences**: chain followups to deliver an exact sequence of messages from the testing agent, turn by turn, without needing any conditions to match — the sequence fires automatically regardless of what the main agent says The `condition` field must be an integer referencing the `id` of the previous condition. ```json theme={null} { "id": 2, "type": "action_followup", "condition": 1, "action": "Also mention that you need a confirmation email", "fixed_message": false } ``` `action_followup` does **not** fire immediately after condition X — it fires on the **next turn**, after the main agent has replied to condition X. The `condition` field holds the `id` (integer) of the condition whose turn triggers this followup. ## Action vs Fixed Message The `action` field can be used in two ways, controlled by the `fixed_message` boolean: ### Using `action` with `fixed_message: false` When `fixed_message` is `false`, the `action` field provides instructions that the testing agent interprets to generate a natural response. ```json theme={null} { "id": 1, "type": "standard", "condition": "The agent asks for your name", "action": "Provide your name as John Smith", "fixed_message": false } ``` The testing agent might say: "My name is John Smith" or "Sure, it's John Smith" or "John Smith" ### Using `action` with `fixed_message: true` When `fixed_message` is `true`, the `action` field contains the exact text that the testing agent will say, word-for-word. ```json theme={null} { "id": 1, "type": "standard", "condition": "The agent asks for your name", "action": "My name is John Smith", "fixed_message": true } ``` The testing agent will say exactly: "My name is John Smith" ### When to Use Each * Natural, varied responses * Testing agent adaptability * When exact wording doesn't matter * Exact phrases required * Testing specific keywords * Compliance testing * Reproducible test cases * First message (id: 0) — always required * Actions containing XML tags `fixed_message` is required on every condition and must be explicitly set to `true` or `false`. It determines how `action` is interpreted: as instructions (`false`) or as the exact message to send (`true`). ## Supported Tags Conditional Actions supports a variety of special tags in the `action` field to control conversation flow and behavior. **Important**: Tags are only supported when `fixed_message` is set to `true`. They will not work with `fixed_message: false` (instruction-based actions). Tags can be combined with text and other sibling tags. They run from left to right; do not nest tags inside one another, except inside a regional `...` block. `` and `` remain whole-action tags. ### Communication Tags Mark a message as an IVR (Interactive Voice Response) message that cannot be interrupted. ```json theme={null} { "id": 1, "type": "standard", "condition": "The call is answered", "action": "", "fixed_message": true } ``` The agent cannot interrupt while this message plays. `` must be the **entire action** — it cannot be combined with other text or tags in the same action string. **DTMF digits appear in the transcript when using ``.** When a scenario contains the `` tag, any DTMF digits pressed by the main agent (the agent being tested) are captured and appear in the transcript. This lets you write conditions that detect the exact digit pressed — for example, `"The main agent pressed 1"` — rather than relying on speech detection alone. Both `` and `` can appear in any condition, not just `id: 0`. **Attributes:** * `text`: The IVR message to play (required) `` and ` Wrap a span of the action so everything inside plays to completion — nothing the main agent says can interrupt it. Content is unrestricted: spoken text, ` Play a voicemail greeting with beep. ```json theme={null} { "action": "" } ``` Or just a beep without greeting: ```json theme={null} { "action": "" } ``` `` must be the **entire action** — it cannot be combined with other text or tags in the same action string. **Attributes:** * `text`: Voicemail greeting message (optional) - if omitted, only plays beep; if provided, cannot be empty End the call immediately. ```json theme={null} { "action": "Thank you for your help " } ``` **Attributes:** None ### Speech Control Tags **`` vs ``** — both add pauses, but behave differently: | | `` | `` | | ------------------ | ----------------------------------------------------------- | ----------------------------------------- | | Interruptible | ✅ Yes — main agent can interrupt | ❌ No — testing agent won’t be interrupted | | After interruption | Condition matching restarts after main agent stops speaking | N/A | | Background noise | Continues to play during the pause | Does **not** play during the pause | Use `` when you want the conversation to feel natural and allow the main agent to jump in. Use `` when you need a guaranteed delay before the next message. Add a pause in speech. **Interruptible** — if the main agent speaks during the silence, the testing agent stops immediately and condition matching restarts once the main agent finishes. Background noise continues to play during the pause. ```json theme={null} { "id": 3, "type": "standard", "condition": "The agent offers time slots", "action": "Let me think I'll take the 3pm slot", "fixed_message": true } ``` **Attributes:** * `time`: Duration of silence (required) - format: "Xs" where X is a number (e.g., "1s", "2.5s") Wait before sending the next message. **Not interruptible** — the testing agent will not be interrupted during a hold, regardless of what the main agent says. Background noise does not play during a hold. ```json theme={null} { "action": "Please wait Are you still there?" } ``` Can have multiple hold tags in one action: ```json theme={null} { "action": "First part Second part Final part" } ``` **Attributes:** * `time`: Duration to wait before next message (required) - format: "Xs" where X is a number (e.g., "5s", "10s") Spell out text letter by letter (e.g., API → A—P—I). ```json theme={null} { "action": "My reference code is ABC123" } ``` **Attributes:** None - this is a wrapping tag that encloses the text to be spelled Control the speed of speech (ratio: multiplier of base speed). ```json theme={null} { "action": " I need to talk quickly about this" } ``` Must be at the start of the message. **Attributes:** * `ratio`: Speed multiplier (required) - Valid range: **0.8 to 1.2**
Examples: `"1.2"` for 20% faster, `"0.8"` for 20% slower Control the volume/loudness (ratio: multiplier of base volume). ```json theme={null} { "action": " This is important!" } ``` Must be at the start of the message. **Attributes:** * `ratio`: Volume multiplier (required) - Valid range: **0 to 2**
Examples: `"1.5"` for 50% louder, `"0.5"` for 50% quieter Switch the testing agent's TTS voice mid-call. A self-closing tag without `text` changes every later utterance — including later conditions — until another persistent `` tag changes it. This is the **persistent** form. This is how you put more than one speaker in a single simulated call: a caller handing the phone to a family member, a supervisor taking over, or a different person picking up. ```json theme={null} { "conditions": [ { "id": 2, "condition": "agent asks to speak to the account holder", "action": "Hold on, let me get my husband. Hi, this is Mark speaking.", "type": "standard", "fixed_message": true } ] } ``` The switch applies between utterances, so any text before the tag is spoken fully in the previous voice. **Regional voice:** Add `text` to speak only that text in the selected voice; the previous voice resumes immediately afterward. ```json theme={null} { "action": " How can I help?", "fixed_message": true } ``` When regional speech contains inline tags such as ``, use an opening and closing block instead. Nested inline tags are allowed only inside this regional voice block. ```json theme={null} { "action": "Hi, this is the manager. How can I help?", "fixed_message": true } ``` Do not combine `text` with the opening/closing form. All `` tags require `fixed_message: true`. **Attributes:** * `provider`: Voice provider (required) - `cartesia` or `11labs`. Must be the **same provider the evaluator already runs on**. * `id`: Voice ID (required) - must belong to that provider: | Provider | Voice ID format | Example | | ---------- | ----------------------- | -------------------------------------- | | `cartesia` | UUID | `b7d50908-b17c-442d-ad8d-810c63997ed9` | | `11labs` | Alphanumeric, no dashes | `21m00Tcm4TlvDq8ikWAM` | * `model`: TTS model (optional) - omit it to use the provider's default: `sonic-3.5` for Cartesia, `eleven_turbo_v2_5` for ElevenLabs. **The provider cannot change mid-call.** `provider` states which provider the voice ID belongs to so a mismatched pair is caught when you save the evaluator, rather than failing mid-call. To use a voice from a different provider, change the evaluator's voice configuration instead. ### Interaction Tags Send DTMF (touch-tone) digits. ```json theme={null} { "id": 2, "type": "standard", "condition": "The agent asks for account number", "action": " I've entered my account number", "fixed_message": true } ``` Simulates pressing phone keypad buttons. **Attributes:** * `digits`: DTMF digits to send (required) - e.g., "123", "456#", "\*9" For caller data such as an account number or PIN, reference the test profile instead of hardcoding the digits — ``. The value is resolved per run and any formatting in it is stripped before the tones are sent. See [DTMF testing](/documentation/guides/testing-agents/dtmf-testing). Trigger an SMS to be sent. ```json theme={null} { "action": " I've sent the code" } ``` **Attributes:** * `text`: SMS message content to send (required) Send an app-level [RTVI](https://github.com/rtvi-ai) client message to a Pipecat agent under test. Use this when the customer's app would send an event such as opening a form, submitting data, or requesting session arguments during the conversation. ```json theme={null} { "id": 2, "type": "standard", "condition": "The agent asks for the job number", "action": "", "fixed_message": true } ``` The tag is silent: any text before or after it is spoken separately. Client messages are sent in the order they appear in the action. **Attributes:** * `t`: App-defined RTVI message type (required). Use the exact type your agent expects; Cekura does not invent or validate application-specific types. * `d`: Optional app-defined payload. JSON is decoded before it is sent. Use single quotes around the attribute when the JSON contains double quotes, as in the example above. This tag is available for Pipecat agents that receive RTVI client messages. It requires `fixed_message: true`, like all tags in conditional actions. Interrupt the main agent after a specified time and deliver the message. ```json theme={null} { "id": 2, "type": "action_followup", "condition": 1, "action": " Please listen carefully to these instructions", "fixed_message": true } ``` The testing agent will interrupt the main agent after 3 seconds and speak this message. `` has two requirements: 1. The condition must have `type: "action_followup"` 2. The tag must appear at the **very start** of the action string **Attributes:** * `time`: Duration to wait before interrupting (required) - format: "Xs" where X is a number (e.g., "3s", "5.5s") ### Environmental Tags Add continuous background sounds during a portion of speech. ```json theme={null} { "action": "Hi, I'm calling about my order" } ``` **Attributes:** * `sound`: Sound name (required) - see supported sounds below * `volume`: Volume level (optional) - default applies if not specified **Supported sounds:** | Sound name | Description | | -------------------- | ----------------------- | | `office-ambience` | Office environment | | `coffee-shop` | Coffee shop chatter | | `kitchen-noise` | Kitchen sounds | | `home-chatter` | Home background voices | | `vacuum-cleaner` | Vacuum cleaner | | `dog-barking` | Dog barking | | `baby-crying` | Baby crying | | `keyboard-typing` | Keyboard typing | | `coughing` | Coughing sounds | | `background-printer` | Printer noise | | `quiet-room` | Near-silent room | | `air-conditioner` | AC hum | | `construction-site` | Construction noise | | `busy-street` | Street traffic | | `airport-boarding` | Airport gate | | `inside-car` | Moving car interior | | `inside-train` | Moving train interior | | `public-park` | Park ambience | | `rain-thunder` | Rain and thunder | | `windy-day` | Wind | | `restaurant` | Restaurant ambience | | `shopping-mall` | Shopping mall | | `stadium-crowd` | Crowd noise | | `standard-hiss` | White noise hiss | | `static-radio` | Radio static | | `fan-buzz` | Fan buzz | | `ship-humming` | Low ship hum | | `two-people-talking` | Background conversation | | `train-station` | Train station hall | | `holding-on-song` | Hold music | The sounds above are available via the `` tag in evaluator actions. To use a **custom audio file URL** as background noise (e.g., `https://your-domain.com/noise.mp3`), use the **Custom URL** option in the Background Noise dropdown when [creating or editing a personality](/documentation/advanced/creating-custom-personalities) — no tag required. Play a one-shot sound effect (does not loop). ```json theme={null} { "action": "Hold on one moment" } ``` **Attributes:** * `sound`: Sound name (required) - supported: `office`, `beep`, `cough1`, `cough2` * `volume`: Volume level (optional) * `time`: Duration in ms (optional) Simulate packet loss on the network connection. ```json theme={null} { "action": " Testing under poor network" } ``` **Attributes:** * `packet_loss`: Packet loss percentage (required) - e.g., `"5"` = 5% loss ## Custom Functions Functions let the testing agent fetch **live data from your systems during the call** and use it in what it says — look up an order, pull an account record, then respond with the real values instead of invented ones. Declare functions once in a top-level `functions` array (a sibling of `role` and `conditions`), then use them from any condition's `action`. ```json theme={null} { "role": "You are a customer checking on an order", "functions": [ { "name": "lookup_order", "type": "rest_api", "auto_run": true, "config": { "method": "GET", "url": "https://api.example.com/orders/{{test_profile.order_id}}", "headers": { "Accept": "application/json" }, "timeout_seconds": 5, "response_mapping": { "status": { "path": "$.data.status", "default": "unknown" }, "eta_days": "$.data.eta" } } } ], "conditions": [ ... ] } ``` ### Function fields Unique name used in tags and placeholders. Letters, digits, `_`, `-`; up to 64 characters. The function type. Currently `rest_api` — an HTTP call to your API. When `true` (the default), the function runs once automatically at the start of the call, in the background — its values are ready before the conversation needs them. Set `false` to run the function only when a condition invokes it with a `` tag. `GET` or `POST`. The endpoint to call. Supports `{{test_profile.*}}` substitution. Must be an `http(s)` URL that is **publicly reachable** — internal and loopback addresses are refused at call time. Request headers, e.g. `{ "Authorization": "Bearer ..." }`. Values must be strings or numbers. Query parameters appended to the URL. Values must be strings or numbers. Request body (`POST` only). Objects and arrays are sent as JSON; strings are sent as-is. Between 1 and 30 seconds. Keep it short — a slow endpoint delays the turn that's waiting on it. Names the values you want out of the JSON response — see [Response mapping](#response-mapping-jsonpath) below. ### When a function runs | Trigger | Runs | Choose it when | | -------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto_run: true` (default) | Once, at the start of the call, in the background | The data will be needed at some point in the call — it's fetched before any turn waits on it | | `` tag in an action | The moment that condition fires | The call must happen at a specific point in the flow (e.g. only after the agent asks), or you need to **re-fetch** — a tag always makes a fresh request | The tag is allowed on any condition except the First Message (`id: 0`), on both `standard` and `action_followup` conditions, fixed or non-fixed. ### Using the response Two ways to get fetched values into the testing agent's replies: * **Value placeholder — `{{function.lookup_order.status}}`** (fixed messages only). Substitutes one mapped output into the exact spoken text: ```json theme={null} { "id": 2, "condition": 1, "action": "My order shows as {{function.lookup_order.status}}.", "type": "action_followup", "fixed_message": true } ``` * **Non-fixed actions — no placeholder needed.** When `fixed_message` is `false`, the testing agent is automatically given the function's results (your named outputs plus the response) and phrases its reply from them: ```json theme={null} { "id": 2, "condition": 1, "action": "Ask about the order and mention its real status.", "type": "action_followup", "fixed_message": false } ``` A single fixed action can both invoke and use a function — put the tag **before** the placeholder. The function completes before the text is spoken: `"Let me check. It shows as {{function.lookup_order.status}}."` ### Response mapping (JSONPath) Each `response_mapping` entry gives a short output name to a value in the JSON response. An entry is either a path string, or an object with `path` and a `default`: ```json theme={null} "response_mapping": { "status": "$.data.status", "eta_days": { "path": "$.data.eta", "default": "a few" } } ``` | Syntax | Meaning | | -------------------- | ------------------------------------------------- | | `$.data.status` | Nested key | | `$.items[0].sku` | Array index (negative indexes allowed) | | `$.meta["order-id"]` | Bracket notation for keys with special characters | Wildcards, filters, and recursive descent are **not** supported — point each output at one exact value. ### Chaining functions A function's `config` can reference an earlier function's outputs, so one call can feed the next — for example, look up a customer, then verify with the fetched name: ```json theme={null} "functions": [ { "name": "lookup", "type": "rest_api", "config": { "method": "GET", "url": "https://api.example.com/orders/ORD-1", "response_mapping": { "customer": "$.customer_name" } } }, { "name": "verify", "type": "rest_api", "auto_run": false, "config": { "method": "GET", "url": "https://api.example.com/verify?name={{function.lookup.customer}}", "response_mapping": { "verified": "$.ok" } } } ] ``` Make sure the referenced function has already run — via `auto_run` or a tag on an earlier condition. ### If the call fails A failed function never breaks the conversation. On a timeout, an error response, or an unreachable URL: * Mapped outputs fall back to their declared `default`. * A placeholder with **no** default is spoken as-is (`"...status is {{function.lookup_order.status}}"`) — declare defaults for anything a fixed message references. * On non-fixed actions, the testing agent is told the lookup failed, so it doesn't invent values. ### Rules * Function `name`s must be unique; `` tags and `{{function.*}}` placeholders must reference a declared function. * Placeholders require `fixed_message: true`, and the key must be an output declared in that function's `response_mapping`. * Neither tags nor placeholders may appear on the First Message (`id: 0`) — use `auto_run` and reference the values from a later condition. For a full scenario showing both flows — a fixed-message placeholder and a non-fixed grounded reply from one `auto_run` function — see [Example 5](#example-5-live-data-via-a-custom-function) below. ## Attached Audio Attach a pre-recorded audio clip to a condition and the testing agent **plays the recording instead of speaking the text with TTS** when that condition fires. Use it when the exact voice, accent, tone, or non-speech sound matters — reproducing a real caller's recording, a specific IVR prompt, background audio a synthetic voice can't recreate, or a regression case captured from a live call. Audio can only be attached to a **fixed-message** condition (`fixed_message: true`). It is not available on instruction-based (`fixed_message: false`) conditions — those are meant to vary, and a recording is fixed by definition. If you only need a **second speaker** rather than a specific recording, use the [`` tag](#supported-tags) instead — it keeps the dialogue generated so the conversation can still adapt. ### How it works 1. You upload an audio file to a specific condition (from the editor UI or the API). 2. Cekura **transcribes it automatically** in the background — this is why a clip is briefly *processing* before it's ready to use. 3. Cekura inserts a managed `