A Scenario is the runtime definition of one call type for one project. "Inbound booking", "outbound reservation reminder", "post-visit feedback" — each is a separate scenario. A project can have any number of them.
This page covers the user-facing settings on the Scenario edit page. The underlying mechanics — slot validators, intercept ordering, tool dispatch — are the platform's job and do not surface in the UI unless you explicitly use the script editor.
Direction
A scenario is either inbound or outbound.
- Inbound scenarios run when a call lands on a phone number your project owns. The platform picks the matching scenario based on routing rules (typically the called number).
- Outbound scenarios run when you trigger a call — from the UI, the API or a CSV upload. You name the scenario explicitly per trigger.
A single project mixes both freely. A restaurant might have one inbound scenario (taking bookings) and one outbound (24-hour confirmation calls).
Goal
Every scenario has a primary Goal — the single outcome that defines success. The agent treats every conversation as a search for this outcome.
A goal carries:
- A description in plain language — what success looks like
- Success criteria — typically a specific tool call with valid arguments (e.g.
book_reservationcalled with a date, time, party, name and phone) - Constraints — rules the agent must obey (e.g. "do not book parties larger than 8 — escalate")
- Escalation rules — when to hand off to a human
- Tone — one sample utterance + one rule that anchors the agent's voice
- Priority — for projects with multiple goals, which one wins on a conflict
Industry packs ship goals you can use as-is or edit. You can also write your own from scratch.
Slots
A Slot is a typed structured value the agent collects during the call. Common examples: partySize: integer, bookingDate: date, customerName: string, phone: phone.
Slots are declared in the scenario. The agent fills them in any order that feels natural in the conversation — it is not a strict survey. Validators (optional) sanity-check each value as it is captured. The agent re-asks when a slot is invalid; you do not write that re-ask flow.
A slot is either required (the agent will not finish without it) or optional (it captures it if the caller mentions it, otherwise skips). Required slots block goal completion.
Steps and prompts
A scenario is composed of Steps — slot_collection, say, branch, and a few others. Most simple scenarios are a single slot_collection step that owns all the slots; the agent fills them in one flowing conversation.
Each step carries a prompt fragment that is composed into the agent's working prompt for that step. You edit the fragment in the scenario editor. The platform composes the full prompt for you — your goal, your slots, your knowledge base, the conversation history, the tool list — so the fragment is short and focused on the step's specifics.
Intercepts
Intercept events are named moments in the conversation where you can attach a custom handler. The most common ones:
- Silence — caller has not spoken for N seconds; default is to nudge politely; you can override.
- Interruption — caller starts speaking while the agent is mid-sentence; default is to yield; you can override.
- Language switch — caller switches to a different supported language mid-call.
- Before tool call — runs before any tool is invoked; useful for last-minute validation or logging.
- Slot filled — fires when a specific slot gets a value; useful for downstream side effects.
- Before session end — fires right before the agent hangs up; last chance to send a confirmation.
Intercepts are declared by the platform and the industry packs come with sensible defaults. You only edit them when you have a specific edge case to handle.
Voice and tone
A scenario inherits its voice settings from the project. You can override per scenario:
- Voice — male / female / neutral, and the underlying TTS voice
- Liveliness — quiet / neutral / animated — the energy level
- Tone — one sample utterance the agent should sound like, plus one rule. Per ADR-0048, this anchors a specific register much better than a cluster of adjectives.
The agent honours these consistently across the call.
Tier
Every scenario has a pricing tier — Economy, Standard or Premium — which selects the provider stack we use for that scenario and scales the per-call rate accordingly. See Billing for the rate card.
Most projects start on Standard (the default) and only move scenarios up or down when they have a reason — Economy for high-volume FAQ, Premium for high-stakes sales.
Testing
Every scenario you build is testable in the browser before you connect a phone number. The Test caller in the Live tab spins up a WebRTC session against the current scenario; you can step through edge cases, the platform records every test call and you replay them later. Test calls are not billed.
Where to go next
- Plugins — the integrations your scenario calls into
- Knowledge base — the data the agent grounds its answers in
- Outbound — how to trigger scenarios programmatically
- Webhooks — how to subscribe to scenario events