Create and test a Miravoice survey

Use the Miravoice Survey Designer to build voice-based surveys, test how the AI agent conducts them, publish them to phone campaigns, and review the responses collected from calls.

This guide is for users who create or manage Miravoice survey projects.

After reading it, you should be able to:

• Build a survey with questions and sections
• Add answer choices and hidden response codes
• Control survey flow with skip logic, display conditions, and termination conditions
• Use variables and FAQs to make the AI agent more accurate and helpful
• Test and publish a survey to a phone number

How a Miravoice project works

A Miravoice project contains everything needed to run a voice survey: the survey design, publishing setup, and response data.

Each project has three main areas.

Design

Use Design to build and test the survey.

This is where you create questions, organize sections, configure answer choices, add logic, define variables, manage FAQs, choose the survey language and voice, and test the call experience before publishing.

Publish

Use Publish to connect the survey to phone-based workflows.

A published survey can be used for:

• Outbound calls, where Miravoice calls respondents
• Inbound calls, where respondents call a dedicated phone number to complete the survey

Results

Use Results to review what happened after calls begin.

Results include call activity, overview statistics, recordings, transcripts, and structured response data from each completed call.

Build the survey structure

Open the Editor

1. Open a project.
2. Go to Design.
3. Open the Editor tab.

The Editor is where you create the survey script and define how respondents move through it.

Understand the Editor layout

The Editor has three main areas:

• Left menu: Add questions, add sections, copy items, and delete items.
• Center panel: Edit questions and sections while configuring survey logic.
• Right panel: Review the project structure and search the survey.

For long surveys, use the right-side project structure to see an overview of the questions and sections in order.

Questions and sections

A survey is made from questions and sections.

Questions

Questions are the prompts the AI voice agent asks the respondent.

Each question has:

• A Question ID, used to identify the question in logic and results
• A Question Type, which controls what kind of answer is collected
• Question Text, which is read by the AI voice agent
• Answer choices, when the question type uses them
• Optional advanced settings, such as display conditions or termination conditions

Sections

Sections group questions together.

Use sections to:

• Organize related questions
• Add introductory text before a group of questions
• Randomize the order of questions in a group
• Create nested groups of questions or sections

Sections are the main way to randomize question order in Miravoice.

Add a question

1. Open the Editor tab.
2. In the left menu, select Add Question.
3. Enter a Question ID.
4. Choose a Question Type.
5. Enter the Question Text.
6. Add answer choices, if the question type uses them.
7. Configure any advanced settings.
8. Select Save.

New questions are added to the end of the survey.

Write question text for voice

Miravoice surveys are spoken aloud, so write questions the way a person would ask them.

Prefer:

Do you currently rent or own your home?

Avoid:

Please indicate your current homeownership status.

The first version is easier to understand over the phone and easier to answer naturally.

Add a section

1. Open the Editor tab.
2. In the left menu, select Add Section.
3. Enter a Section ID.
4. Add Preamble Text, if the agent should introduce the section before asking its questions.
5. Add questions or nested sections to the section.
6. Select Save.

Example preamble

Next, I’m going to ask a few questions about your recent healthcare experience.

Use preamble text when respondents need context before a group of questions.

Choose the right question type

Choose the question type based on the answer you need to collect.

Single Choice questions

Use a Single Choice question when the respondent should choose one answer from a list.

Single choice questions are useful for:

• Yes / No questions
• Screening or eligibility questions
• Choosing one category
• Selecting one preferred option

Example

Question text:

Do you currently rent or own your home?

Visible answers:

• Rent
• Own

Hidden answers:

• Don’t know
• Refused

Single choice questions support visible answers, hidden answers, answer IDs, answer ordering, answer-level logic, and question-level advanced settings.

Rating Scale questions

Use a Rating Scale question when the respondent should choose one answer from an ordered list, like a Likert Scale.

Rating scale questions are similar to single choice questions, but the answer choices have a meaningful order.

Use rating scale questions for:

• Satisfaction ratings
• Agreement scales
• Quality ratings
• Likelihood scales
• Frequency scales

Example

Question text:

How would you rate the quality of the service you received?

Visible answers:

• Poor
• Fair
• Good
• Very good
• Excellent

Rating scale questions support display conditions, termination conditions, interpretation settings, transcription corrections, and Skip Answer Intro.

Open-Ended questions

Use an Open-Ended question when the respondent should answer in their own words.

Open-ended questions are useful for:

• Feedback
• Explanations
• Comments
• Reasons for a previous answer
• Responses that should not be limited to predefined choices

Example

What is the main reason you feel that way?

Open-ended questions do not use visible answer choices, so Read Answer Choices is disabled.

Hidden answers for open-ended questions

Open-ended questions can still use hidden answers such as Don’t know or Refused.

These answers are not read to the respondent, but they can still be captured and coded.

Interpretation for open-ended questions

Use Loose interpretation when any spoken response should be accepted.

Use Strict interpretation when the response must meet a defined requirement. When strict interpretation is enabled, use Acceptable Answer Requirements to describe what counts as a valid response.

Example acceptable answer requirement

Accept answers that explain a specific reason for the respondent’s satisfaction rating. Do not accept unrelated comments.

Listening pause length

Use Listening Pause Length to control how long Miravoice waits (in seconds) after the respondent pauses before moving to the next question.

The default value is typically 3.

For longer open-ended responses, use a longer pause so respondents have time to think and continue speaking.

Numerical questions

Use a Numerical question when the respondent should provide a number.

Numerical questions are useful for:

• Age
• Income
• Household size
• Counts or quantities

Example

How many people currently live in your household?

Numerical questions do not use visible answer choices.

Numerical validation settings

Use numerical validation to make sure the answer is usable.

Common settings include:

• Acceptable Answer Requirements: Describes what counts as a valid answer.
• Minimum Value and Maximum Value: Require the number to fall within a range.
• Context: Helps Miravoice understand what the number represents.
• Integer Only: Requires a whole number.
• Allow Don’t Know and Allow Refused: Accept and code these responses instead of treating them as invalid.
• Re-Prompt Phrase: Tells the respondent how to correct an invalid answer.

When you use acceptable answer requirements, set interpretation to Strict so Miravoice validates the response.

Example validation

For a 1-to-100 rating:

• Minimum value: 1
• Maximum value: 100
• Integer only: enabled
• Re-prompt phrase: Please answer with a whole number between 1 and 100.

Matrix / Grid questions

Use a Matrix or Grid question when you need to ask several related prompts that share the same answer choices.

A matrix question has:

• Rows, which are the individual prompts
• Columns, which are the shared answer choices

Example: Yes / No matrix

Introductory text:

For each of the following, please say yes or no.

Rows:

• Do you own a car?
• Do you own a bicycle?
• Do you use public transit?

Columns:

• Yes
• No

This saves time because you define the Yes / No choices once and reuse them across multiple rows.

Use matrix questions for select-all behavior

Matrix questions are often the best way to create voice-friendly select-all-that-apply questions.

In a phone survey, asking respondents to “select all that apply” from a long list can be confusing. Instead, ask each option as a separate Yes / No row.

This approach is often called one-hot encoding.

Example: Voice-friendly select-all question

Instead of asking:

Which of the following races do you identify with? White, African-American, Asian...

Ask:

For each of the following, please say yes or no as to whether you identify with this race.

Then ask each item separately:

• White: Yes / No
• African-American: Yes / No
• Asian: Yes / No

This is easier for respondents to answer by voice and easier to code consistently in the results.

Configure answer choices

Single choice, rating scale, and matrix questions use answer choices.

Visible answers

Visible answers are presented to the respondent. Depending on the question settings, the AI voice agent may read them aloud.

Use visible answers for the choices respondents are expected to choose from.

Hidden answers

Hidden answers are not read as part of the answer list, but they can still be captured and coded.

Use hidden answers for responses such as:

• Don’t know
• Refused
• Not applicable

Hide an answer

1. Find the answer in Visible Answers.
2. Select the eye icon next to the answer.
3. Confirm that the answer moves to Hidden Answers.

Show a hidden answer

1. Find the answer in Hidden Answers.
2. Select the show-answer or hidden-eye icon next to the answer.
3. Confirm that the answer moves back to Visible Answers.

Use answer templates

Answer templates let you add common answer sets quickly.

Templates may include:

• Yes / No
• True / False
• Accept / Decline
• Agree / Disagree

Available templates depend on the question type. For example, rating scale questions may offer different templates than single choice questions.

Answer choice properties

Each answer choice has properties that control how it is identified, read, and used in logic.

Answer ID

The Answer ID identifies a specific answer choice.

Default IDs often appear as a1, a2, a3, and so on.

Answer IDs are used in display conditions, termination conditions, skip logic, variables, and results.

Order

The Order field controls the order in which answer choices are read.

Use numbers such as 1, 2, 3, and 4 for a fixed order.

Use values such as random or random0 to randomize answer order.

Visible or hidden status

Each answer choice can be visible or hidden.

Visible answers are presented to the respondent. Hidden answers are not presented, but can still be captured and coded.

Control survey flow

Miravoice gives you several ways to control which questions are asked and what happens after respondents answer.

Use the simplest control that fits the workflow.

Use answer-level skip logic

Use answer-level skip logic when one answer should send the respondent to a specific next question.

Example

Q0 asks:

Do you currently own a car?

If the respondent answers Yes, continue to car ownership questions.

If the respondent answers No, skip to the next relevant section.

Answer-level skip logic is best for simple branching. For more complex logic, use display conditions.

Use display conditions

A Display Condition determines whether a question should be asked.

Miravoice checks the display condition before reading the question:

• If the condition is true, the question is asked.
• If the condition is false, the question is skipped.

Display conditions use Miravoice’s conditional expression engine.

Example: Ask a follow-up question after a Yes answer

Suppose Q0 asks whether the respondent owns a car, and the answer ID for Yes is a1.

To ask Q1 only when the respondent answered Yes to Q0, set the display condition for Q1 to:

Q0 == a1

If the respondent answers a1, Miravoice asks Q1. Otherwise, Miravoice skips Q1.

Example: Use OR logic

To ask a question if either Q1 is answered with a2 or Q2 is answered with a3, use:

Q1 == a2 OR Q2 == a3

Use parentheses when you need to group logic clearly.

Use termination conditions

A Termination Condition determines whether the survey should end early.

Miravoice checks termination conditions after the respondent answers the question.

Use termination conditions when the survey should end based on a combination of responses or more complex logic.

Answer-level termination vs. termination conditions

Use answer-level termination when one specific answer should end the survey.

Use a Termination Condition when the survey should end only if a broader condition is true.

Termination message

Add a termination message to control what the AI voice agent says when the survey ends.

Example:

Thank you for your time. Those are all the questions we have today.

Understand logic order

Miravoice evaluates logic in this order:

1. Check the question’s display condition.
2. If the display condition is true or empty, ask the question.
3. Capture the respondent’s answer.
4. Check the question’s termination condition.
5. If the termination condition is true, read the termination message and end the survey.
6. If the termination condition is false, continue to the next eligible question.

Remember: display conditions happen before a question is asked. Termination conditions happen after a question is answered.

Randomize survey content

Randomization helps reduce order effects by varying the order in which respondents hear questions or answer choices.

Miravoice supports randomization for:

• Questions inside a section
• Sections inside another section
• Answer choices within a question
• Groups of answer choices

Randomize question order in a section

1. Open the section.
2. Add the questions or nested sections that should be randomized.
3. Enable Randomize Question Order.
4. Save the survey.

Miravoice randomizes the items inside that section.

Because sections can contain questions or other sections, you can randomize individual questions, entire groups of questions, or both.

Example: Randomize sections and questions

You have sections A, B, C, and D.

You want:

• The sections to be asked in random order
• Questions inside Section A to be randomized
• Questions inside Section B to stay in a fixed order

To do this:

1. Create a parent section.
2. Add sections A, B, C, and D inside it.
3. Enable Randomize Question Order on the parent section.
4. Enable or disable Randomize Question Order inside each child section, depending on how that section should behave.

Randomize answer choices

To randomize answer choices for a question, set the Order field for each answer that should be randomized to:

random

Miravoice reads those answer choices in a random order.

Randomize answer choices within groups

Use grouped randomization when answers should be randomized within groups, but the groups themselves should stay in a fixed sequence.

Use values such as:

random0
random1
random2

Answers with the same randomization value are randomized within that group. Groups are read in sequence.

Example: Randomize candidates within groups

For a presidential poll, you may want to read major-party candidates first, in random order, followed by minor-party candidates, also in random order.

Configure the answer order like this:

Miravoice reads the random0 group first, with the candidates randomized within that group. Then it reads the random1 group, also randomized within the group.

Configure how answers are interpreted

Question-level advanced settings control how the AI voice agent reads answer choices and validates responses.

Read Answer Choices

Use Read Answer Choices to control whether the AI voice agent reads the visible answer choices aloud.

Enable it when the respondent should hear the available choices.

Disable it when the question text already makes the expected answer clear or when reading the choices would sound repetitive.

Loose interpretation

Use Loose interpretation when Miravoice should accept natural variations of an answer.

For single choice and rating scale questions, loose interpretation lets Miravoice map common wording to the intended answer.

Example: For a Yes / No question, “yeah” can be interpreted as “yes.”

For open-ended questions, loose interpretation generally accepts any response.

Strict interpretation

Use Strict interpretation when the respondent’s answer must closely match the expected response or meet a defined requirement.

Example: For a Yes / No question, “yeah” may not be accepted as “yes.” The respondent may need to say “yes.”

For open-ended and numerical questions, strict interpretation can validate the response against acceptable answer requirements.

Improve speech recognition and pronunciation

Voice surveys depend on two related but different behaviors:

• Transcription: What Miravoice hears and converts into text.
• Pronunciation: How the AI voice agent speaks the survey text.

Use transcription corrections when Miravoice hears a response incorrectly. Use variables when the AI voice agent says a word incorrectly.

Use transcription corrections

Use Transcription Corrections to correct words or phrases that the speech-to-text system commonly mishears for a specific question.

Example

A question asks:

Do you rent or own your home?

During testing, you notice that “rent” is sometimes transcribed as “ranch.”

Add a transcription correction so that “ranch” is treated as “rent” for that question.

Use transcription corrections only when the incorrect transcription is common, predictable, and clearly maps to the intended answer.

Use variables for pronunciation

Variables can improve pronunciation because they substitute text before the voice agent reads it.

This is useful for:

• Names
• Counties or locations
• Acronyms
• Brand names
• Long or uncommon words
• Words the AI voice agent consistently mispronounces

Example

If the voice agent mispronounces “Peacock,” create a variable named:

peacock

Set the value to a phonetic spelling, such as:

PEE-KOK

Then use the variable wherever the word should be read:

{{peacock}}

Miravoice substitutes the phonetic spelling when the survey runs.

Use variables for dynamic text

Use the Variables tab to create text that can change during the survey.

Variables are useful when you want to:

• Change wording based on earlier answers
• Reuse the same text in multiple places
• Adjust phrasing for different respondent paths
• Improve pronunciation

Variables use the same conditional expression engine as display conditions and termination conditions.

How variables work

A variable has:

• A Name
• A Default Value
• Optional Conditional Values

The default value is used when no condition applies. A conditional value is used when its condition evaluates to true.

Create a variable

1. Open the Variables tab.
2. Create a new variable.
3. Enter a variable name.
4. Enter a default value.
5. Add conditional values, if needed.
6. Select Save.

Use a variable

To use a variable, place the variable name inside double curly braces:

{{variable_name}}

Miravoice replaces the variable with the correct value when the survey runs.

Variables can be used in supported text fields, including question text, answer text, and FAQs.

Example: Change the agent name based on a condition

Create a variable named:

agent_name

Set the default value to:

Lisa

Add a conditional value:

Bob

With the condition:

Q2 == a2

Then write:

Hi, my name is {{agent_name}}.

If the condition is false, the agent says:

Hi, my name is Lisa.

If the condition is true, the agent says:

Hi, my name is Bob.

Add FAQs for respondent questions

Use FAQs to define approved answers the AI voice agent can give when respondents ask questions during the survey.

By default, the AI voice agent avoids answering questions outside the survey script so it does not bias the respondent. FAQs give the agent a controlled knowledge base for common respondent questions.

How FAQs work

Each FAQ includes:

• An ID
• A Question the respondent might ask
• An Answer the AI voice agent should give

Respondents do not need to use the exact FAQ wording. Miravoice can recognize similar wording and respond with the matching approved answer.

Add an FAQ

1. Open the FAQs section.
2. Add a new FAQ.
3. Enter an FAQ ID.
4. Enter the question a respondent might ask.
5. Enter the answer the AI voice agent should provide.
6. Select Save.

Example FAQ

Question:

Will I be compensated for the survey?

Answer:

Unfortunately, we are not able to compensate you for the survey.

If a respondent asks whether they will be paid, reimbursed, or compensated, the AI voice agent can use this approved answer.

Start with recommended FAQs

Miravoice provides recommended default FAQs in the console.

Use those defaults as a starting point. Add new FAQs for questions respondents ask during testing or live calls.

You can copy or move FAQs between projects by selecting them or using drag-to-select. Use the ctrl-c (Windows) or cmd-c (Mac) keyboard shortcuts to copy the FAQs and then the ctrl-v (Windows) or cmd-v (Mac) keyboard shortcuts to paste the FAQs into the new project.

Configure survey settings

Use the Settings tab to configure survey behavior for your project.

Common settings include:

• Survey language
• Voice configuration

Language

Choose the language the survey should use.

Make sure the question text, answer choices, FAQs, and pronunciation variables have the appropriate translations for the selected language.

Note: Though Miravoice is multilingual, currently the Miravoice self-service frontend console only supports English, though additional languages are being added soon to the UI. For multilingual support, contact the Miravoice team and we’ll help you set up your project.

Voice configuration

Choose the AI voice style that will read the survey.

After selecting a voice, test the survey to confirm that the script sounds natural and that important names, terms, and answer choices are pronounced correctly.

Save, test, and publish

Use this workflow before launching a survey.

1. Save the survey

Select Save to store your latest draft changes.

Save regularly. If you leave the Editor without saving, you may lose recent changes.

2. Test the survey

Select Test and complete a live test run.

During testing, check that:

• Questions are read clearly
• Answer choices sound natural
• Hidden answers are captured correctly
• Variables are substituted correctly
• Display conditions work as expected
• Termination conditions work as expected
• Skip logic sends respondents to the correct question
• FAQs answer common respondent questions appropriately
• The selected voice sounds appropriate for the audience

3. Fix and retest

Update the survey based on what you find during testing. Then save and test again.

Repeat until the survey sounds natural and behaves correctly.

4. Publish the survey

When the survey is ready, select Publish.

Miravoice takes you to the Publish page, where you can publish the survey to a campaign to facilitate inbound or outbound calling workflows.

5. Review results

After calls begin, go to the Results page to review call activity, recordings, transcripts, and structured response data.

Other Editor tools

Version History

Use Version History to view previously published versions of the survey and revert to an older version if needed.

Version history is saved when you publish a survey. If the survey has not been published, version history may only show the current version.

Search

Use the search menu on the right side of the Editor to find survey content quickly.

You can search by:

• Question keywords
• Question text
• Question ID

Search is especially useful for long surveys.

Troubleshooting

A question is not being asked

Possible causes:

• The question has a display condition that evaluates to false.
• A previous answer triggered skip logic to another question.
• The question is inside a randomized or nested section and appears later than expected.

What to try:

1. Check the question’s display condition.
2. Confirm the previous question IDs and answer IDs used in the condition are correct.
3. Review answer-level skip logic on earlier questions.
4. Test the survey path again.

The survey ends earlier than expected

Possible causes:

• An answer-level termination setting is enabled.
• A question-level termination condition evaluates to true.
• The condition uses an incorrect question ID or answer ID.

What to try:

1. Review answer-level advanced settings.
2. Review question-level termination conditions.
3. Confirm the termination message and condition are configured on the intended question.
4. Remember that termination conditions are checked after the respondent answers the question.

The AI voice agent accepts an answer too broadly

Possible cause:

• The question uses loose interpretation.

What to try:

1. Change interpretation to Strict.
2. For open-ended or numerical questions, add acceptable answer requirements.
3. For numerical questions, add minimum and maximum values if applicable.
4. Add a re-prompt phrase to guide the respondent.

The AI voice agent rejects valid answers

Possible causes:

• The question uses strict interpretation.
• Acceptable answer requirements are too narrow.
• Numerical validation settings are too restrictive.

What to try:

1. Review the interpretation setting.
2. Broaden the acceptable answer requirements.
3. Check minimum, maximum, and integer-only settings.
4. Test with several realistic respondent answers.

A word is mispronounced

What to try:

1. Create a variable with a phonetic spelling.
2. Replace the original word in the survey text with the variable using double curly braces.
3. Test the survey again.

A response is transcribed incorrectly

What to try:

1. Confirm the incorrect transcription is common and predictable.
2. Add a transcription correction for the specific question.
3. Test again to make sure the correction does not change valid responses incorrectly.

Related topics

• This documentation is not comprehensive yet, as there are features that Miravoice supports that are not documented here. More is coming soon.