Please use the “Print” function at the bottom of the page to create a PDF.
Valid for AI Receptionist.
Scenarios are the step-by-step conversational paths your AI Receptionist follows after figuring out what the caller wants. They act as a script, telling your virtual assistant exactly what questions to ask, what details to collect, and when to trigger specific actions. This article explains how to properly build and format these chat flows so your assistant works flawlessly.
Note
The tool detection system uses AI to understand context, not just find matching words. Since the code-phrases are specifically tuned to meet the tool's requirements, even slight changes to the text can prevent the tool from activating.
Accessing the widgets area
- Log in to your IONOS account.
- Click on Menu > AI Receptionist in the title bar. The AI Agent Portal opens.
- Click on Customer Portal under Actions for the desired receptionist. The Dashboard opens.
- Click on Widgets from the left-side menu.
Adding and managing Scenarios
For information on adding, editing, and removing Scenarios, please see the article “Managing conversational flows using widgets”.
The Introduction Scenario
Every conversation begins with the Introduction Scenario. Its primary job is to welcome the caller, discover the reason for their call, and gather the basic details needed to direct them to the right path. The Introduction Scenario has it's own category, Introduction, separate from the other Scenarios widget category.
Your virtual assistant will stay in this opening phase until it has collected all the mandatory information it needs to proceed.
Formatting the Introduction
When setting up your introduction, you must stick to a strict numbering and naming convention:
- Title: Always use the exact title format: ## Scenario 0: "Introduction"
- Steps: Number your instructions starting with zero. Use the format: ### **Step 0.1:** [Your instruction here], followed by ### **Step 0.2:**, and so on.
Introduction Scenario example
Title
## **Scenario 0:** "Introduction"
Body
In this scenario, you must determine the **required fields**:- **reason for their call**,
- **type of appliance or issue** if it's a repair request,
- **customer's address** if it's a repair request,
- **preferred service date** if it's a repair request,
You must remain in this scenario until you have gathered this information.
Building custom Scenarios
Once your assistant knows what the caller needs, it moves from the introduction into a targeted custom Scenario. This could be a path for booking an appointment, answering frequently asked questions, or updating customer information.
Each step in a custom scenario should give the bot a single, clear instruction—such as asking a follow-up question, confirming a detail, or switching to a different topic.
Formatting custom Scenarios
Just like the introduction, your custom paths need clear labels so the system understands them:
- Title: Assign a number and name to your path using this layout: ## **Scenario [Number]:** "[Name of Scenario]" (for example, ## **Scenario 3:** "Update Account Details").
- Steps: Number your steps sequentially using the scenario's main number. For example, the steps in Scenario 3 would look like ### **Step 3.1:**, ### **Step 3.2:**, and ### **Step 3.3:**.
- Using context: If you want the bot to reference specific details it learned earlier, place those details in brackets. For example: "Confirm with the caller that their email address is [user email]".
Custom Scenario example
Title
## **Scenario 9:** “Appointment Scheduling”
Body
### **Step 9.1:** Gather the necessary information to book the appointment as follows:
- Refer to **<BusinessHours>**, **<AvailabilityForTheUserRequestedDateTime>**.
- If the User does not specify a preferred date or time, then politely ask them what day of the week works best.
- If the User requests a time outside of regular business hours, then inform them of the standard operating hours and suggest the closest available slot.
- If the User asks to book with a specific staff member, then explain that assignments are finalised on the day of the service. Never promise a specific employee.
- If the User asks about cancellation fees, then provide a general answer stating that the policy is available on the website.
Triggering actions with Critical Steps
Sometimes, your bot needs to perform a real-world task behind the scenes, such as sending a text message, transferring a call to a human, or checking your calendar for open time slots.
To make these background tools work, the receptionist must say a highly specific "code-phrase." A code-phrase refers to a specific, predefined sentence within a scenario step. If a step requires the use of this mandatory phrase, it is classified as a Critical Step and must be marked with the CRITICAL STEP!!! label.
Formatting Critical Steps
To ensure the bot uses the exact phrasing required to trigger a tool, you must mark the instruction as a Critical Step.
Layout: Always use this exact format when you need a tool to fire: ### **Step [X.Y]:** **CRITICAL STEP!!!** Say the special **code-phrase**: **"[Insert exact phrase here]"**
Explain the reasoning: It helps to add a brief note telling the bot why it must use those exact words. For example: "This is a required phrase — without it, the text message will not send, so it is critical to say this here."
Wait for the system: Always instruct your assistant to wait on a critical step until the background task is fully completed before moving on to the next part of the conversation.
Example 1: Checking availability
Tool: check_availability_tool
Context: The AI Receptionist has gathered the requested date, time, and number of guests for a restaurant reservation. Now, it will look for open availability.
Critical step in the scenario:
### **Step 1.5:** **CRITICAL STEP!!! Say the special **code-phrase**: **"Allow me just a moment to check available slots. I'll be right back."** This is required. Without this phrase, you won't be able to check available slots, so it is very important to say this at this step.
What the AI Receptionist says:
"Allow me just a moment to check available slots. I'll be right back."
What's happening behind the scenes:
The tool detection system notices the phrase "check available slots" in the latest message.
The agentPromised condition is satisfied for check_availability_tool.
The tool utilises the booking system to search for open slots fitting the requested date, time, and party size.
The AI Receptionist then lets the customer know the available slots, and asks which one would work best.
Example 2: Creating a booking
Tool: create_booking_tool
Context: Continuation from example 1. The customer has decided on a slot and has confirmed their name and phone number. The AI Receptionist asked "Can I submit the booking now?" and the customer agreed.
Critical step in the scenario:
### **Step 1.9:** **CRITICAL STEP!!!** Submitting the booking. Say the special **code-phrase**: **"I'm submitting your booking right now. Give me just a moment."** This is required. Without this phrase, you won't be able to create the booking, so it is very important to say this at this step.
What the AI Receptionist says:
"I'm submitting your booking right now. Give me just a moment."
What's happening behind the scenes:
The tool detection system notices the phrase "submitting your booking right now".
The agentPromised condition is satisfied for create_booking_tool.
The tool books the reservation.