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 model. The underlying mechanics — slot validators, intercept ordering, tool dispatch — are the platform's job and do not surface 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 the called number and the project's intent routes.
- Outbound scenarios run when you trigger a call through the API. 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 works towards a Goal — the 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 — most commonly a specific tool call with valid arguments (e.g. a reservation tool called with a date, time, party size, name and phone), or a set of slots that must be filled
- 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 plus a liveliness level that anchor 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 shape your own with the Copilot.
Slots
A Slot is a typed structured value the agent collects during the call. The types: string, integer, datetime, phone, email, boolean and enum. Common examples: partySize: integer, bookingDate: datetime, 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; when a value fails validation, the slot goes back to pending with the rejection reason and the agent re-asks. 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 and branch. 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. The platform composes the full prompt for you — your goal, your slots, your knowledge base, the conversation history, the tool list — so the fragment stays short and focused on the step's specifics.
Intercepts
Intercept events are named moments in the conversation where a script handler can run. The most useful ones:
- Silence — the caller has not spoken for a while; the default is to nudge politely; you can override.
- Interruption — the caller starts speaking while the agent is mid-sentence; the agent yields by default.
- Before / after tool call — runs around any tool invocation; useful for last-minute validation or logging.
- Slot filled — fires when a specific slot gets a value; useful for downstream side effects.
- Session start / session end — bookends of the call.
- Webhook received — an external system pushed an event into the live session (see Webhooks).
Intercepts are declared by the platform and the industry packs come with sensible defaults. You only touch them when you have a specific edge case to handle.
Voice and tone
Voice settings live on the project and the goals:
- Voice — female or male, set per project. The platform maps it to the matching voice of whichever provider tier the scenario runs on.
- Voice style — a free-form instruction on the project ("calm and unhurried", "energetic but professional").
- Tone and liveliness — on the goal: one sample utterance the agent should sound like, plus a liveliness level (formal / neutral / warm). One concrete utterance anchors a register much better than a cluster of adjectives.
The agent honours these consistently across the call.
Tier
Every scenario runs on a pricing tier — Economy, Standard, Premium or Enterprise — which selects the provider stack we use for that scenario and scales the per-call rate accordingly. The project sets a default tier (Standard unless you change it); a scenario can override it. See Billing and the pricing page for the rate card.
Most projects stay on Standard and only move scenarios up or down with a reason — Economy for high-volume FAQ, Premium or Enterprise for high-stakes sales. Enterprise also includes enterprise-level support and an SLA.
Testing
Every scenario you build is testable in the browser before you connect a phone number. The Test call card on the project Overview spins up a WebRTC session against the current scenario; you can step through edge cases, and every test call is recorded and playable afterwards. Test calls are free during your trial and never require a wallet top-up.
After a test call, open the session record: the transcript and the tool-call trace show exactly what the agent did, and Discuss with AI lets you turn what you saw into a concrete configuration change.
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