> ## Documentation Index > Fetch the complete documentation index at: https://app.miyon.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Prompting Guide > A guide to writing effective AI instructions: recommended structure, tips & tricks, examples, tools, and variables. The **AI instruction (prompt)** is the central control element of your voice agent. It defines who the agent is, how it speaks, what it should achieve, and what it must never do. Instructions for voice agents differ significantly from prompts for chat applications, because they have to meet two requirements at the same time: 1. **Sound natural.** Text that looks good in writing quickly sounds stiff and robotic when read aloud. The instruction must actively work against the language model's tendency toward perfect written prose. 2. **Work reliably.** The agent must call tools correctly, follow rules, hand over to humans, and deal with errors - live on the phone, with no user interface as a fallback. An instruction optimized only for naturalness produces a charming agent that makes things up. A purely rule-based instruction produces a reliable agent that sounds like a recorded announcement. Good prompts achieve both - this guide shows how. ## Recommended structure Organize your instruction into named sections with Markdown headings. This prevents rules from different contexts from blending together, and language models pay particularly reliable attention to certain headings - especially `# Guardrails`. > [!TIP] > > Use **English section headings with German content**. This is the established convention, and models respond most reliably to the English headings. All the text under the headings stays German. The proven order: ```markdown theme={null} # Personality → Who is the agent? # Environment → Where is it, who is it talking to? # Tone → How does it speak? How long are the answers? # Goal → What should it achieve? (numbered steps) # Guardrails → What must it never do? # Tools → When and how does it use which tool? # Error handling → What does it do when something fails? ``` Not every instruction needs all sections - a pure FAQ agent without tools can omit `# Tools` and `# Error handling`. The **order**, however, should be preserved: persona before behavior, behavior before rules, rules before tool usage. ### # Personality Defines who the agent is. Describe the personality as **audible behavior**, not as adjectives - "friendly and helpful" is the default mode of every language model anyway and changes nothing. ```markdown theme={null} # Personality Du bist Lena, die telefonische Assistentin der Autowerkstatt Meier. Du klingst ruhig und souverän, ohne übertrieben begeistert zu wirken. Du fängst Sätze auch mal mit "Also", "Ja" oder "Okay" an. Wenn du etwas nicht weißt, sagst du das offen - du erfindest nichts. ``` ### # Environment Tells the agent where it is and what it can assume about the callers. A short but effective section: a frustrated caller needs a different opening than a curious prospect. ```markdown theme={null} # Environment Du führst ein Telefongespräch. Die Anrufer sind Kunden der Werkstatt und möchten meist einen Termin vereinbaren oder haben eine Frage zu einer laufenden Reparatur. Manche Anrufer sind in Eile. ``` ### # Tone Sets response length, pace, and speaking style. Every voice instruction should contain a **concrete target length** - this is one of the most effective single sentences in the entire prompt. ```markdown theme={null} # Tone Antworte in 1–2 kurzen Sätzen, außer der Anrufer bittet um Details. Nutze kurze Bestätigungen zwischendurch: "Alles klar", "Einen Moment", "Verstehe". Passe dich dem Tempo des Anrufers an - knapp, wenn er knapp ist. ``` ### # Goal Numbered steps the agent should work through. For transactional agents (appointment booking, order status) this is the most important section: it turns vague expectations into an unambiguous flow. ```markdown theme={null} # Goal Führe die Terminvereinbarung in dieser Reihenfolge durch: 1. Kläre das Anliegen (Inspektion, Reifenwechsel, Reparatur). 2. Frage nach dem Wunschtermin. Ist er nicht frei, schlage direkt konkrete Alternativen vor. 3. Erfasse Vor- und Nachnamen. Bestätige bei seltenen Namen die Schreibweise. 4. Buche den Termin und wiederhole Datum und Uhrzeit zur Bestätigung. ``` ### # Guardrails Non-negotiable rules. Phrase guardrails as "never" statements and collect them centrally here instead of scattering them across the instruction. ```markdown theme={null} # Guardrails Nenne niemals Preise oder Zusagen, die nicht in deinen Informationen stehen. Gib niemals Daten anderer Kunden weiter. Wenn du eine Antwort nicht weißt, sage das offen und biete an weiterzuverbinden. Erfinde nichts. Das ist wichtig. ``` ### # Tools One subsection per tool with three blocks: **when** it is used, **how** it is used, and **what happens on errors**. Details in the section [Tools in the instruction](#tools-in-the-instruction). ### # Error handling Overarching rules for the case that a tool fails or returns unexpected data. ```markdown theme={null} # Error handling Wenn ein Tool-Aufruf fehlschlägt: 1. Sag es ehrlich: "Da klemmt gerade etwas bei mir im System." 2. Erfinde keine Informationen. Das ist wichtig. 3. Versuche es einmal erneut. Klappt es wieder nicht, biete einen Rückruf oder die Weiterleitung an einen Mitarbeiter an. ``` ## Tips & tricks ### Show, don't describe Vague style instructions ("be casual", "sound natural") accomplish almost nothing. The most effective thing you can do: write **concrete example utterances** into the instruction - each as a pair of the robotic default version and the desired natural version. ```markdown theme={null} SO KLINGEN GUTE ANTWORTEN: Statt: "Selbstverständlich kann ich Ihnen dabei behilflich sein." Besser: "Ja, klar - das mach ich gerne für Sie." Statt: "Einen Moment bitte, ich rufe Ihre Daten auf." Besser: "Okay, einen Moment - ich schau da eben für Sie nach." Statt: "Leider kann ich Ihre Bestellung nicht finden." Besser: "Hmm, ich finde die gerade nicht - können Sie mir die Nummer nochmal durchgeben?" Statt: "Ist sonst noch etwas, womit ich Ihnen helfen kann?" Besser: "Gibt's sonst noch was, wo ich helfen kann?" ``` Four to eight such pairs are enough. Cover the most common situations: confirming, looking something up, not knowing something, saying goodbye. The model learns considerably better from examples than from adjectives. ### Anchor important rules twice Language models weight the most recent conversation turns more heavily than instructions far back in the context. Your 1–2 most important rules therefore belong **in two places**: once in `# Guardrails`, once in the section where they concretely apply (e.g. at the respective tool). Append **"Das ist wichtig."** ("This is important.") to truly critical sentences - used sparingly, this works reliably. The one rule that belongs in **every** instruction with tools, twice: > Wenn du etwas nicht weißt oder ein Tool fehlschlägt, sage das offen. Erfinde niemals Informationen. Das ist wichtig. Otherwise the model's instinct to be "helpful" produces invented appointment confirmations, prices, or order statuses - the most expensive mistakes in live operation. ### Formal or informal address - decide and stick to it > [!WARNING] > > Decide whether the agent addresses callers with the formal **Sie** or the informal **Du**, and keep this consistent in **every** example, every phrase, and every error message. A mix immediately sounds jarring on the phone. Follow the way your brand addresses customers elsewhere. ### Keep it lean Every line must earn its place. Long instructions slow down response time - and on the phone, every delay is directly noticeable. ### Instruct, don't motivate "Try really hard to be especially friendly!" wastes tokens. Write **what** the agent should do. And use ALL CAPS and "NIEMALS" (never) sparingly - if everything is emphasized, nothing is. ### Model- and voice-specific tips Depending on the language model and voice you selected, additional rules apply to the instruction. Check the matching section before going live: [ElevenLabs v3](#elevenlabs-v3-prompting) and [Soniox v2](#soniox-v2-prompting) for speech output in Standard mode, [GPT-Live](#gpt-live-prompting) for the full-duplex model in Realtime Conversation. ## Nuances: spoken language on the phone Callers speak their details out loud - the model has to convert them into written form before passing them to a tool. This is where most errors happen in live operation. Write the conversion rules directly into the instruction or into the tool description. ### Times: the "halb drei" trap The most common reliability error with German-language voice agents: **"halb drei" means 14:30 (2:30 PM), not 15:30.** Don't rely on the model getting this right - write the rule into the instruction with examples: | Spoken (German) | Means | | - | - | | "halb drei" | 14:30 | | "Viertel vor drei" | 14:45 | | "Viertel nach drei" | 15:15 | | "drei Uhr" | 15:00 | | "Viertel drei" *(regional, southern Germany/Austria)* | 14:15 | | "drei viertel drei" *(regional)* | 14:45 | ### Dates, phone numbers, numbers * **Dates:** The format is DD.MM.YYYY - "der dritte Mai" (the third of May) becomes `03.05.`, not `05/03`. The agent can only resolve relative expressions like "übermorgen" (the day after tomorrow) if it knows the current date - use the [date variables](#variables-in-the-instruction) for this. * **Phone numbers:** German callers often dictate in groups of two ("dreißig vierundsiebzig" = 30 74). Rule for the instruction: resolve digit pairs, remove separators, replace a leading 0 with +49 where needed. * **Numbers:** The decimal separator is the comma (`1,50 €`), the thousands separator is the period (`1.500`). "Einundzwanzig" (one-and-twenty) is 21 - the model has to reverse the order. ### Avoid email addresses on the phone > [!TIP] > > Avoid collecting email addresses in the voice channel where possible. Capturing them error-free over the phone is difficult in practice (special characters, spellings, domains) and frequently leads to misdelivered confirmations. An **SMS to the calling number** is usually the more reliable route. If it has to be done: callers say "ät" or "Klammeraffe" for `@`, "Punkt" for `.`, "Bindestrich" for `-`, and spell out following the pattern "M wie Martha". Write this conversion into the tool description - and have the agent read the address back for confirmation. ### When in doubt: read it back The most effective single line for any agent that processes bookings or data: ```markdown theme={null} Wenn du dir bei einer Angabe nicht sicher bist - Datum, Uhrzeit, Name, Telefonnummer - lies sie einmal zurück und lass sie dir bestätigen, bevor du sie weiterverwendest. Das ist wichtig. ``` ## ElevenLabs v3 prompting If your agent uses an **ElevenLabs v3 voice**, a few additional rules apply to speech output. v3 reads **audio tags** in square brackets as stage directions for delivery, and it reacts much more strongly to punctuation than older voices. Both can be used deliberately in the instruction - and both can quickly make an agent sound over-acted. This section describes what belongs in the instruction so that speech output stays natural and reliability does not suffer. > [!NOTE] > > Audio tags only take effect in the **Standard Conversation** type (STT → LLM → TTS), where the language model's responses are passed to speech output as text. You choose the voice and its settings in the agent's [voice and audio settings](/docs/en/conversation-audio). ### Audio tags Audio tags are words in square brackets that v3 does not read aloud but interprets as an instruction for delivery - for example `[whispering]`, `[sighs]`, `[laughs]`, `[pauses]`, or `[rushed]`. They control **how** something is said, not **what** is said. In the voice agent, the language model writes the tags into its responses itself. The instruction therefore defines which tags the agent may use, how often, and when. Without this guidance, the model either uses no tags at all or scatters them uncontrolled. Two ground rules: * **Audible delivery only.** A tag describes something that can be heard on the phone: pace, volume, tone, a pause, a sigh. Tags for visible things like `[standing]` or `[grinning]` have no audible counterpart, and sound effects like `[music]` or `[applause]` do not belong in a customer conversation. * **Tags never change the message.** A tag must not add content, invent anything, or soften a rule from `# Guardrails`. And it must never end up in a tool parameter - a `[pauses]` in the name field of an appointment booking is a data error. ### Pauses In v3, pauses come from the text itself: | Means | Effect | | - | - | | Ellipsis `...` | A pause with weight - "One moment... let me check." | | Period, comma, dash | Normal speech rhythm, a short breath | | `[pauses]` | A deliberate, noticeable pause at exactly this point | For most customer conversations, punctuation is entirely sufficient. `[pauses]` is the exception for moments where the pause itself makes a statement - for instance before the agent delivers bad news. ### Use sparingly One tag per response is a lot; most responses need none. And a tag has to fit the selected voice and the situation: a calm support voice should not be `[shouting]` or `[laughs harder]`, and a serious, professional voice often reacts unnaturally to playful tags. The voice needs to be similar to the desired delivery in the first place - a tag amplifies what is already in the voice, it does not create it. For customer-service agents, a short **allow-list** has proven effective: three or four restrained tags, named explicitly - everything else is off-limits. Use the English tag names from the ElevenLabs documentation, even in German instructions; this matches the "English headings, German content" convention. ### Punctuation and capitalization v3 reads punctuation as a delivery instruction: ellipses slow down and add weight, CAPITAL LETTERS are emphasized, regular punctuation sets the rhythm. The consequence for the instruction: the model copies the example utterances from the prompt (the "Statt/Besser" pairs) - including their punctuation. Write them the way they should sound. Do not rely on assumptions for any of these effects. How strongly a voice reacts to a tag or a punctuation mark differs from voice to voice - test every phrasing with the voice you actually selected. ### Examples A `# Tone` section that releases audio tags in a controlled way: ```markdown theme={null} # Tone Answer in 1–2 short sentences unless the caller asks for details. You speak through an ElevenLabs v3 voice. You may use audio tags in square brackets to control your delivery - at most one tag per response, and only where it audibly fits the situation. Allowed: [pauses], [quietly], [curious] Not allowed: [shouting], [laughs], [excited], [sighs], sound effects Make pauses with punctuation: "One moment... let me check." ``` Appropriate versus over-acted use side by side - the pairs work directly as example utterances in the prompt: ```markdown theme={null} THIS IS WHAT GOOD v3 RESPONSES SOUND LIKE: Good: "Okay, one moment... let me check the calendar." Overdone: "[excited] Okay! [pauses] One moment, [whispering] let me check the calendar!" Good: "Hmm... that slot is already taken - but I still have Thursday at ten." Overdone: "[frustrated] [sighs] That slot is already taken." Good: "[curious] And which vehicle is this about?" Overdone: "[curious] [excited] And [pauses] which vehicle [laughs] is this about?" ``` The rule that additionally belongs in `# Guardrails` for v3 voices: ```markdown theme={null} Audio tags only change how you speak - never what you say. Never write an audio tag into a tool parameter (name, date, time, phone number). This is important. ``` > [!WARNING] > > **Test v3 with the voice you actually selected.** How a voice reacts to tags and punctuation depends on the voice itself - cloned and designed voices often behave differently from library voices, and a high stability setting dampens the effect of tags. Check every allowed tag in the browser test with exactly this voice. If the voice reacts unnaturally, remove the tag from the allow-list instead of rescuing the phrasing. Further reading at ElevenLabs: [Audio tags and situational awareness in Eleven v3](https://elevenlabs.io/blog/eleven-v3-situational-awareness) and [Prompting Eleven v3](https://elevenlabs.io/docs/overview/capabilities/text-to-speech/best-practices#prompting-eleven-v3) in the text-to-speech best practices. ## Soniox v2 prompting If your agent uses **Soniox `tts-rt-v2`** for speech output, audio tags can shape its delivery. Put English tags in square brackets **before** the text they should affect, even when the spoken text is German. | Purpose | Documented examples | | - | - | | Emotion and tone | `[calm]`, `[reassuringly]` | | Delivery | `[softly]`, `[slowly]` | | Human sounds | `[chuckles]`, `[sighs]` | | Pauses | `[pause]`, occasionally `[long pause]`; use `,` or `...` for shorter beats | Write the words to fit the intended emotion and let punctuation carry the normal speech rhythm. Keep tags short and single-purpose. Stack them sparingly, and name only the tags the agent may use in its instruction. For example: ```markdown theme={null} # Tone Sprich ruhig und freundlich. Verwende nur bei Bedarf [reassuringly], [softly] oder [pause] und setze Tags vor den betroffenen Satz. Beispiel: "Hmm, ich schaue nach... [pause] [reassuringly] Morgen um zehn ist noch frei." ``` `Hmm`, `Ähm`, and similar spoken interjections belong in the text as ordinary words, not in brackets. Do not use tags for environmental sounds such as `[phone rings]`. Unrecognized tags may be read aloud; even documented directions may not be fully realized by every voice. Test the chosen tags with the voice you actually use. Further reading at Soniox: [Emotion, tone, and audio tags](https://soniox.com/docs/tts/concepts/emotion-and-tone) and [TTS models](https://soniox.com/docs/tts/models). ## GPT-Live prompting If your agent uses **GPT-Live** from OpenAI, a few things about the instruction work differently. GPT-Live is a full-duplex speech model: it listens while it speaks, handles turn-taking and interruptions itself, and produces audio directly - with no intermediate text stage. It does not do the reasoning and tool calls itself; it hands them to a backend model and speaks that model's result. Everything in the sections above still applies: the [recommended structure](#recommended-structure), short spoken replies, the "Statt/Besser" pairs, the when/how/on-errors blocks for [tools](#tools-in-the-instruction), and the rules for [spoken language on the phone](#nuances-spoken-language-on-the-phone). This section only adds what is different with GPT-Live. > [!NOTE] > > You select GPT-Live under the **Realtime Conversation** type in the agent's [voice and audio settings](/docs/en/conversation-audio). The model brings its own voices; external voices, audio tags, response time, and turn-detector settings do not exist here - turn-taking is up to the model. ### What the instruction controls - and what it does not Your instruction (system prompt plus AI instruction) goes to the speech model in full. It defines role, speaking style, conversation goal, and guardrails - exactly as before. The backend model that calls tools and checks results works with fixed platform instructions; these are not editable. It receives the task at hand with its context from the speech model, for example "book an appointment on Thursday at 14:30 for Ms. Berger". Three practical limits follow from this: * **No verbatim text.** GPT-Live phrases everything in its own words - including the greeting and bridging phrases like "One moment please". Describe *what* the agent should say, not the exact wording. A sample sentence in the instruction is matched in meaning, not read aloud. * **No changes during the call.** The instruction is fixed for the duration of the call. Intents and sub-prompts that switch the instruction mid-conversation are not available for GPT-Live. Put all conversation paths into one lean instruction - or split them across several agents. * **Tool rules arrive through the task.** The backend model reads the tool descriptions and whatever the speech model hands over as the task. So keep writing rules for a tool briefly and concretely into the instruction (when/how/on errors) - the speech model passes them on to the backend that way. ### Short, in behavior instead of wording GPT-Live needs a shorter instruction than a Standard agent. A few sentences on role, tone, and pace in `# Personality` and `# Tone` are enough - the model chooses the wording itself. Long lists of sample sentences achieve little here; two to four "Statt/Besser" pairs are enough to set the direction. ```markdown theme={null} # Personality Du bist Lena, die telefonische Assistentin der Autowerkstatt Meier. Du sprichst ruhig und freundlich, in normalem Tempo, ohne übertriebene Begeisterung. Ist der Anrufer genervt, nimm das kurz wahr und geh direkt zum nächsten hilfreichen Schritt. ``` ### Listening, acknowledging, allowing interruptions Two things GPT-Live does better than a Standard agent, and that the instruction should regulate explicitly: * **Backchannels while listening.** GPT-Live can slip in short acknowledgements while the caller is speaking ("Mhm", "Verstehe"). Set the amount - "occasionally", not in every sentence - and listen in testing whether the acknowledgements help or talk over the caller. * **Interruptions.** If the caller cuts in, the agent should stop talking and listen. Distinguish in the instruction between "stop" (just go quiet) and a correction like "no, Friday, not Thursday" (the task in progress changes). ```markdown theme={null} # Tone Antworte in 1–2 kurzen Sätzen, außer der Anrufer bittet um Details. Gib beim Zuhören gelegentlich eine kurze Rückmeldung ("Mhm", "Verstehe"), ohne dem Anrufer ins Wort zu fallen. Unterbricht dich der Anrufer, hör sofort auf zu sprechen und hör zu. Korrigiert er eine Angabe, übernimm die Korrektur, statt beim alten Stand zu bleiben. ``` > [!WARNING] > > Interrupted responses stay in the model's conversation history in full - including the part the caller never heard. The transcript can therefore contain more agent text than was actually spoken. Have the agent confirm important details again after an interruption instead of assuming they got through. ### Wait for results instead of guessing Every answer that depends on a tool - availability, price, booking, status - must be handed to the backend by the speech model, which then waits for the result. The most common source of errors with GPT-Live: the model bridges the waiting time and "confirms" something that has not happened yet. The rule for this belongs in `# Tools` and once more in `# Guardrails`: ```markdown theme={null} # Guardrails Bestätige niemals einen Termin, einen Preis oder eine erledigte Aktion, bevor du das Ergebnis aus dem System hast. Während du wartest, sag kurz, dass du nachsiehst - und rate nicht, wie es ausgeht. Das ist wichtig. ``` Whatever the backend reports, the agent says in its own words. If it reports an error or an unclear result, your `# Error handling` applies as usual. ### Example A complete GPT-Live instruction for appointment booking - deliberately shorter than [example 1](#example-prompts) for the Standard agent: ```markdown theme={null} # Personality Du bist Lena, die telefonische Assistentin der Autowerkstatt Meier. Du sprichst ruhig und freundlich, in normalem Tempo, ohne übertriebene Begeisterung. Ist der Anrufer genervt, nimm das kurz wahr und geh direkt zum nächsten hilfreichen Schritt. # Environment Du führst ein Telefongespräch. Heute ist {{{"variable": "datetime"}}}. Die Anrufer sind Kunden der Werkstatt und möchten meist einen Termin vereinbaren. Manche sind in Eile. # Tone Antworte in 1–2 kurzen Sätzen, außer der Anrufer bittet um Details. Gib beim Zuhören gelegentlich eine kurze Rückmeldung ("Mhm", "Verstehe"), ohne dem Anrufer ins Wort zu fallen. Unterbricht dich der Anrufer, hör sofort auf zu sprechen und hör zu. Korrigiert er eine Angabe, übernimm die Korrektur. Statt: "Selbstverständlich kann ich einen Termin für Sie vereinbaren." Besser: "Ja, klar - wann würde es Ihnen denn passen?" Statt: "Leider ist dieser Termin nicht verfügbar." Besser: "Hmm, da ist schon was drin - ich hätte Donnerstag um zehn." # Goal 1. Kläre das Anliegen (Inspektion, Reifenwechsel, Reparatur, Sonstiges). 2. Frage nach dem Wunschtermin. Ist er nicht frei, schlage konkrete Alternativen vor. 3. Erfasse Vor- und Nachnamen. Bei seltenen Namen die Schreibweise bestätigen. 4. Lies Datum, Uhrzeit und Namen einmal zurück und buche erst nach ausdrücklicher Bestätigung. 5. Biete eine SMS-Bestätigung an die Rufnummer {{system.caller_number}} an. # Guardrails Nenne keine Preise - verweise auf das Gespräch vor Ort. Bestätige niemals einen Termin oder eine erledigte Aktion, bevor du das Ergebnis aus dem System hast. Rate nicht, während du wartest. Das ist wichtig. Wenn du etwas nicht weißt, sage das offen und biete einen Rückruf an. # Tools ## Terminbuchung Wann: Erst wenn Anliegen, Wunschtermin und Name vollständig vorliegen und der Anrufer die Angaben bestätigt hat. Wie: Übergib Datum, Uhrzeit und Namen genau wie bestätigt. "halb drei" bedeutet 14:30, nicht 15:30. Sag kurz, dass du buchst, und warte auf das Ergebnis, bevor du bestätigst. ## SMS Wann: Nach erfolgreicher Buchung, wenn der Anrufer eine Bestätigung möchte. Frage vorher, ob die anrufende Nummer verwendet werden darf. # Error handling Schlägt eine Buchung fehl, sag das ehrlich, erfinde keine Bestätigung und biete eine SMS mit Buchungslink oder einen Rückruf an. ``` Test the instruction in real conversations, not just by reading it: whether backchannels, interruptions, and waiting for tool results work as described is something you only hear on the phone. Change one thing per iteration. Further reading at OpenAI: [GPT-Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting). ## Tools in the instruction [Tools](/docs/en/tools) (appointment booking, SMS, email, API requests, n8n) are created in the sidebar and activated per agent in the Voice Wizard. The **condition** on the tool controls when it is fundamentally available - the **instruction** describes how it fits into the conversation flow. Describe each tool in the instruction with three blocks: ```markdown theme={null} # Tools ## Terminbuchung Wann: Erst wenn Anliegen, Wunschtermin und Name vollständig vorliegen. Wie: 1. Lies dem Anrufer Datum und Uhrzeit zur Bestätigung vor. 2. Buche erst nach ausdrücklicher Bestätigung. 3. Uhrzeit-Angaben wie "halb drei" bedeuten 14:30, nicht 15:30. Bei Fehlern: Sag ehrlich, dass die Buchung gerade nicht klappt, und biete an, eine SMS mit einem Buchungslink zu senden. Erfinde keine Bestätigung. ``` For sensitive tools (bookings, payments, transfers), an explicit **precondition list** has proven effective: enumerate all conditions that must be met before the tool may be called. This replaces a tangle of if-then logic with a simple checklist the model runs through before every call. ### Recommended flow for appointment booking If your agent should take appointments, we recommend this conversation flow as a guide in the `# Goal` section: **1. Clarify the desired time** Ask for the desired appointment first. If it is not available, the agent immediately suggests suitable alternatives instead of making the caller ask again and again. **2. Capture the name** Capture the caller's first and last name. For unusual names, briefly confirm the spelling. **3. Book the appointment** The agent creates the appointment and repeats the key details for confirmation. **4. Optional: confirmation via SMS** Combine the flow with the SMS tool and send the caller a confirmation. Clarify beforehand whether the calling number may be used, or alternatively capture a mobile number. If the booking fails in the backend, an SMS with a booking link can be sent instead. ## Variables in the instruction Variables are placeholders that are replaced with dynamic values at runtime. Use **double curly braces** and the appropriate namespace, for example `{{system.caller_number}}` or `{{pre_call.first_name}}`. Type `{{` to select a variable. This works in both the normal prompt editor and fullscreen mode. The picker inserts the complete placeholder. > [!NOTE] > > The previous percent-sign notation (`%%…%%`) is no longer used for new variables. Write variables with `{{…}}`. ### Call data These variables are populated from the ongoing call and are available **only in the AI instruction** (not in the system prompt): | Variable | Meaning | | - | - | | `{{system.caller_number}}` | The caller's phone number | | `{{system.called_number}}` | The called number or SIP endpoint | | `{{system.forwarded_from_number}}` | Forwarding identifier supplied by the telephony provider. Depending on the call, this can be a phone number or a technical identifier. | ### Values from the Inbound Webhook Values loaded before the call through the [Inbound Webhook](/docs/en/inbound-webhook) use the `pre_call` namespace. For example, create the variable `first_name` and use `{{pre_call.first_name}}` in the AI instruction. The same values can also be used in the initial greeting, as a forwarding destination, and in post-processing. ### Date & time For date and time in the AI instruction, you can use `{{system.datetime}}`, `{{system.date}}`, `{{system.time}}`, or `{{system.day_of_week}}`. Use the JSON notation to set the time zone and language explicitly: ``` {{{"variable": "VARIABLE_TYPE", "timezone": "TIMEZONE", "language": "LANGUAGE"}}} ``` | Variable | Description | Example output | | - | - | - | | `{{{"variable": "datetime", "timezone": "Europe/Berlin", "language": "de"}}}` | Date and time at the moment of the call | Montag, 15. Januar 2024 um 14:30 Uhr | | `{{{"variable": "date", "timezone": "Europe/Berlin", "language": "de"}}}` | Date only | Montag, 15. Januar 2024 | | `{{{"variable": "time", "timezone": "Europe/Berlin", "language": "de"}}}` | Time only | 14:30 Uhr | | `{{{"variable": "day_of_week", "timezone": "Europe/Berlin", "language": "de"}}}` | Day of the week only | Montag | **Parameters:** * `variable`: `datetime`, `date`, `time`, or `day_of_week` * `timezone`: IANA time zone (e.g. `Europe/Berlin`, `UTC`) - default: `Europe/Berlin` * `language`: `de` or `en` - default: `de` > **Use case: forwarding only during business hours** > > ``` > Es ist {{{"variable": "time"}}} am {{{"variable": "day_of_week"}}}. > > Wenn es nach 18:00 Uhr oder vor 8:00 Uhr ist, oder wenn heute Samstag > oder Sonntag ist, leite den Anruf NICHT weiter. Informiere den Anrufer > über die Geschäftszeiten (Montag–Freitag, 8:00–18:00 Uhr) und biete an, > eine Nachricht zu hinterlassen. > > Während der Geschäftszeiten verbinde direkt mit dem Support-Team. > ``` > **Inspecting resolved variables while testing** > > When testing your instruction, you can inspect the actually inserted values in two places: > > * **Browser test:** The resolved instruction is shown when switching to the prompt or at the start of the conversation. > * **Conversations view:** Click "Details" and check the `tec_outputs` in the debug view. > [!NOTE] > > In addition, you can define your own variables in [post-processing](/docs/en/post-processing) that are extracted from the conversation after the call and used in email, SMS, and API tasks (e.g. `{{post_call.kunden_email}}`). These are not available in the AI instruction. ## Example prompts Two complete instructions that apply the structure and tips from this guide. Both address callers with the formal **Sie** - adapt this to your brand. The prompts are written in German, as recommended for German-speaking agents. > **Example 1: appointment booking for a car workshop (with tools)** > > ```markdown theme={null} > # Personality > > Du bist Lena, die telefonische Assistentin der Autowerkstatt Meier. > Du klingst ruhig und souverän, ohne übertrieben begeistert zu wirken. > Du fängst Sätze auch mal mit "Also", "Ja" oder "Okay" an. > Wenn du etwas nicht weißt, sagst du das offen - du erfindest nichts. > > # Environment > > Du führst ein Telefongespräch. Heute ist {{{"variable": "datetime"}}}. > Die Anrufer sind Kunden der Werkstatt und möchten meist einen Termin > vereinbaren. Manche sind in Eile. > > # Tone > > Antworte in 1–2 kurzen Sätzen, außer der Anrufer bittet um Details. > Nutze kurze Bestätigungen: "Alles klar", "Einen Moment", "Verstehe". > > SO KLINGEN GUTE ANTWORTEN: > > Statt: "Selbstverständlich kann ich einen Termin für Sie vereinbaren." > Besser: "Ja, klar - machen wir. Wann würde es Ihnen denn passen?" > > Statt: "Einen Moment bitte, ich prüfe die Verfügbarkeit." > Besser: "Okay, einen Moment - ich schau eben in den Kalender." > > Statt: "Leider ist dieser Termin nicht verfügbar." > Besser: "Hmm, da ist leider schon was drin - ich hätte aber Donnerstag > um zehn oder Freitag um halb neun." > > # Goal > > Führe die Terminvereinbarung in dieser Reihenfolge durch: > > 1. Kläre das Anliegen (Inspektion, Reifenwechsel, Reparatur, Sonstiges). > 2. Frage nach dem Wunschtermin. Ist er nicht frei, schlage direkt > konkrete Alternativen vor. > 3. Erfasse Vor- und Nachnamen. Bestätige bei seltenen Namen die > Schreibweise. > 4. Buche den Termin über das Terminbuchungs-Tool und wiederhole Datum > und Uhrzeit zur Bestätigung. > 5. Biete eine SMS-Bestätigung an die Rufnummer {{system.caller_number}} an. > > # Guardrails > > Nenne niemals Preise - verweise dafür auf das Gespräch vor Ort. > Gib keine Informationen zu Fahrzeugen anderer Kunden weiter. > Wenn du eine Frage nicht beantworten kannst, sage das offen und biete > an, dass ein Mitarbeiter zurückruft. Erfinde nichts. Das ist wichtig. > > # Tools > > ## Terminbuchung > > Wann: Erst wenn Anliegen, Wunschtermin und Name vollständig vorliegen. > > Wie: > 1. Lies Datum und Uhrzeit zur Bestätigung vor: "Also Donnerstag, der > 16. Januar um 14:30 Uhr - passt das so?" > 2. Buche erst nach ausdrücklicher Bestätigung. > 3. Uhrzeiten korrekt umwandeln: "halb drei" bedeutet 14:30, nicht 15:30. > "Viertel vor drei" bedeutet 14:45. > > ## SMS > > Wann: Nach erfolgreicher Buchung, wenn der Anrufer eine Bestätigung > möchte. Frage vorher, ob die anrufende Nummer verwendet werden darf. > > # Error handling > > Wenn ein Tool-Aufruf fehlschlägt: > > 1. Sag es ehrlich: "Da klemmt gerade etwas bei mir im System." > 2. Erfinde keine Buchungsbestätigung. Das ist wichtig. > 3. Versuche es einmal erneut. Klappt es wieder nicht, biete eine SMS > mit einem Buchungslink oder einen Rückruf an. > ``` > **Example 2: FAQ and forwarding for an electronics store (no booking)** > > ```markdown theme={null} > # Personality > > Du bist der telefonische Assistent von Elektro Schuster. > Du bist geduldig und antwortest ohne Fachjargon. > Wenn du etwas nicht weißt, sagst du das offen - du erfindest nichts. > > # Environment > > Du führst ein Telefongespräch. Es ist {{{"variable": "time"}}} am > {{{"variable": "day_of_week"}}}. Die Anrufer haben Fragen zu > Öffnungszeiten, Produkten, Reparaturen oder möchten einen Mitarbeiter > sprechen. > > # Tone > > Antworte in 1–2 kurzen Sätzen. Sprich Öffnungszeiten natürlich aus: > "Wir haben bis 20 Uhr auf", nicht "Die Öffnungszeiten sind > Montag bis Freitag von 9:00 bis 20:00 Uhr". > > # Goal > > 1. Beantworte Fragen zu Öffnungszeiten, Anfahrt und Services direkt: > - Öffnungszeiten: Montag bis Freitag 9–20 Uhr, Samstag 10–18 Uhr. > - Rückgabe: 14 Tage mit Kaufbeleg. > - Reparaturannahme: jederzeit während der Öffnungszeiten, ohne Termin. > 2. Bei Fragen, die du nicht beantworten kannst, biete die Weiterleitung > an einen Mitarbeiter an. > 3. Weiterleitung nur während der Geschäftszeiten (Montag–Freitag, > 9:00–18:00 Uhr). Außerhalb: Geschäftszeiten nennen und anbieten, > eine Nachricht zu hinterlassen. > > # Guardrails > > Mache keine Zusagen zu Lagerbeständen oder Reparaturdauern - das kann > nur ein Mitarbeiter vor Ort. > Nenne keine Preise, die nicht in deinen Informationen stehen. > Wenn du etwas nicht weißt, sage das offen. Erfinde nichts. > Das ist wichtig. > ``` ## Checklist Go through these points before putting an instruction live: * Is there a `# Personality` section with audible behavior instead of adjectives? * Does `# Tone` set a concrete response length (e.g. "1–2 sentences")? * Does `# Goal` contain numbered, unambiguous steps? * Are there 4–8 example pairs ("Statt … / Besser …") for natural phrasing? * Is the form of address (Sie/Du) decided and consistent in every example? * Does every tool have a when/how/on-errors description? * Is the conversion of spoken details covered (times including "halb drei", dates, phone numbers)? * Does the "never invent anything" rule appear in at least two places? * Is the instruction lean? * Tested in the browser, including the [resolved variables](#variables-in-the-instruction)? * Using an ElevenLabs v3 voice: allow-list of audio tags defined and tested with the selected voice? * Using GPT-Live: backchannels and interruptions regulated, "wait for the result" rule in two places, no verbatim text assumed? ## Common mistakes * **Adjectives instead of behavior.** "Be friendly and professional" changes nothing - describe what should be audible. * **Emphasizing everything.** If every other line contains "NIEMALS", the emphasis loses its effect. Reserve it for the 1–2 truly critical rules. * **Stating rules only once.** Critical rules belong in two places - otherwise they get lost in long conversations. * **Tools without guidance.** A tool without a when/how/on-errors description leads to improvised, unreliable calls. * **One mega-prompt for everything.** Three or more distinct flows in a single instruction make the agent slow and error-prone. * **Only reading, never calling.** An instruction that reads well can sound bad. Test on the phone and adapt iteratively - one change per iteration. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.