Skip to main content
A voice agent is only as good as what you write for it. Text that reads well on screen often sounds stiff, long, or confusing when spoken. This guide shows how to write steps, instructions, and scenarios that work for speech, using the tools built into the Callers script editor.

​
How Callers reads what you write

Your agent combines several sources each time it speaks. Knowing which source does what helps you put each piece of content in the right place.
Put each fact or rule in exactly one place. If the same price appears in a step, in Agent Instructions, and in the knowledge base, the agent may quote different versions on different calls.

​
Write for the ear

​
Keep turns short

Aim for one to three short sentences per step. On a call, a contact cannot skim or scroll back. A long turn invites interruptions and makes the agent sound like a recording.

​
Ask one question at a time

End most steps with a single, specific question. Two questions in one turn usually get one answer, and the agent then has to guess which one was answered.

​
End steps with a question

A step that ends on a statement leaves dead air. The contact waits for the agent, the agent waits for the contact, and after a while the agent breaks the silence. Close with a short check such as “Does that work for you?” unless the step ends the call.

​
Prefer specific choices over open questions

“Would Tuesday morning or Thursday afternoon work better?” is easier to answer on the phone than “When would you like to meet?” and gives the agent a clean answer to act on.

​
Bad and better phrasing

Before
Hi {{first_name}}, I’m calling from Acme Insurance because we noticed that your policy is coming up for renewal next month, and we wanted to let you know about some new coverage options and discounts we’re offering this year, which could save you money. Do you have a few minutes, and would you also like to hear about our home bundle?
After
Hi {{first_name}}, this is Sam from Acme Insurance. Your policy renews next month. Do you have two minutes to go over your options?
Spoken formats differ from written ones. Write content the way you want it heard, then confirm on a test call.
For words the agent mishears (product names, surnames, jargon), add them to the speech recognition vocabulary. For words it mispronounces, use the pronunciation dictionary.

​
Use variables to personalize

Insert variables such as {{first_name}} or {{renewal_date}} into steps, instructions, and scenarios with the Variables tag. Values come from your contact upload, the API data field, or a pre-conversation action.
  • Map every variable to a column or field. A variable with no value is spoken as nothing, which can leave a sentence broken.
  • Write sentences that still make sense if an optional variable is empty, or mark the variable as required.
  • Format values in your data the way you want them spoken. A date stored as 2026-11-03 is harder to say naturally than November 3rd. If you can’t change the data, add an instruction such as “Say the renewal date as a month and day.”
See Variables for built-in variables and transcript variables.

​
Script steps or instructions?

Each step can contain spoken text, inline instructions, or both. Decide who writes the words for each step.

Scripted step

You write the exact words. Use it for disclosures, legal lines, prices, and anything approved word for word.

Instruction-driven step

You describe what to say and the agent composes it. Use it when the line depends on data or on what the contact just said.
To add an inline instruction, choose the Instructions tag while editing a step, type the guidance, and press Enter to end the instruction. Avoid giving two sources for the same line. If a step has a full sentence and an instruction that also says what to say, the agent may say both, merge them, or pick a different one on each call.
Great, I can see your balance now. Instruction: Tell the customer their balance and due date, then ask if they want it by SMS.
A behavioral instruction (tone, pacing, a constraint, when to escalate) can sit next to scripted text. A quick test: delete the instruction. If the step still has something complete to say, the instruction is behavioral and can stay.
Use instructions for nuance, not for branching. If the conversation should go in clearly different directions depending on the answer, create a subflow for each answer in the script editor instead of an “if… otherwise…” instruction.

​
Scenarios versus script steps

Script steps cover the path you expect. Scenarios cover what can come up at any time: questions, objections, and edge cases. When a scenario fires, the agent handles it and then returns to where it was in the script. Tips for scenarios:
  • Title each scenario by the trigger (what the contact says), not by the response. “Contact asks about pricing” works better than “Explain pricing.”
  • Start with a direct answer, then hand back with a short question.
  • Keep each scenario self-contained, because the script resumes afterward.
  • For long or changing facts, connect a knowledge base and keep the scenario short.
See Scenarios.

​
Knowledge base or instructions?

Keep knowledge bases focused. Several small, topical knowledge bases retrieve more precisely than one large document. Use clear headings and avoid repeating the same fact in several files. See Knowledge base.

​
Agent Instructions and guardrails

Agent Instructions apply to every step and scenario. A good block covers:
  • Persona: name, company, role, and tone.
  • Response style: short answers, one question per turn, lead with the answer.
  • Prohibited behavior: for example, never read URLs aloud, never promise outcomes, never quote prices that aren’t in the knowledge base.
  • Escalation: when to transfer to a person.
Keep this block short and don’t restate what the script already says. Long, repetitive instructions reduce how closely the agent follows them. For rules that must never be broken, add a guardrail. Guardrails are checked separately from the prompt and can end the conversation, transfer to a person, or regenerate the response.

​
Control pacing and interruptions

Writing is half of it; timing is the other half. These settings let you tune how the agent delivers what you wrote.
Use uninterruptible steps sparingly. A contact who can’t interrupt may talk over the agent or hang up. Keep these steps short.
See Conversation dynamics for patience, interruptions, and no-response settings.

​
Test and iterate

Prompting is iterative. Plan several rounds of test calls before you launch.
1

Test the happy path

Place a Test Call or Web Call from the agent header and follow the main path. Listen for long turns, awkward phrasing, and moments where the agent waits too long or too little.
2

Test the edges

Interrupt the agent, ask off-script questions, give unclear answers, stay silent, and say “not interested.” Check that the right scenarios fire.
3

Test in the target language

If the agent speaks another language or dialect, test in that language. Pronunciation and phrasing problems rarely show up in translation.
4

Read the transcript and listen to the recording

Transcripts show what was said. Recordings show pacing, interruptions, and pronunciation. Use both.
5

Change one thing at a time

Edit one step or setting, test again, and compare. Changing many things at once makes it hard to see what helped.
6

Review real calls after launch

Use Insights mode to find steps where contacts hang up or interrupt, then rewrite those steps first.

​
Checklist

Each step is one to three short sentences and ends with one question (unless it ends the call).
No URLs, long email addresses, or ambiguous numeric dates are spoken.
Every variable has a value source, and sentences still work if optional values are empty.
Each step has one source for its words: scripted text or an instruction, not both.
Scenarios are titled by trigger and cover your most common questions and objections.
Facts live in the knowledge base; behavior lives in instructions; hard limits live in guardrails.
Disclosures use Speak with no interruptions and are kept short.
You’ve tested interruptions, silence, off-script questions, and the target language.

Steps

Step types and per-step settings.

Instructions and guardrails

Agent-wide rules and hard limits.

Latency and conversation quality

Make the agent feel responsive.

Testing your agent

Test calls, chats, and emails.