VoiceTel

Support / VoiceML examples / Build voice and audio prompts with VoiceML

Build voice and audio prompts with VoiceML.

Morpheus offers callers a choice: the red pill or the blue pill. The call shows how a document controls what callers hear: two different voices, a word stressed with emphasis, a line repeated with loop, timed pauses, and a recorded audio clip. It is one document published on voiceml.org, with no application server.

Free trial Text-to-speech guide

What callers hear

  • Two voices

    Morpheus speaks in the built-in male voice; the other lines use the female voice.

  • Emphasis on one word

    “There is no spoon” stresses the last word with <emphasis>.

  • A repeated line

    A wrong key gets “Mister Anderson” twice, from a single <Say loop="2">.

  • A recorded clip

    The red pill plays an audio file of your own with <Play>, between spoken lines.

Before you start

  1. A VoiceML account with a phone number. See VoiceML or start a free trial.
  2. A short audio clip at a public HTTPS URL, as a WAV or MP3 of up to 50 MiB, with a file name that ends in its format. Use audio you have the rights to.

Step 1: Publish the document and point the number at it

Replace AUDIO_URL with your clip’s URL, then publish it at voiceml.org and set the /r/ URL it returns as the phone number’s voice URL. Keep the URL exactly as returned, key included, and don’t post it publicly.

main.xml

<Response>
  {% if Digits == blank %}
    <!-- Morpheus speaks in the built-in male voice -->
    <Gather input="dtmf" numDigits="1" timeout="8" method="POST">
      <Pause length="1"/>
      <Say voice="man">This is your last chance. After this, there is no turning back.</Say>
      <Pause length="1"/>
      <Say voice="man">You take the blue pill, the story ends. You wake up in your bed and believe whatever you want to believe. Press 2.</Say>
      <Pause length="1"/>
      <Say voice="man">You take the red pill, you stay in Wonderland, and I show you how deep the rabbit hole goes. Press 1.</Say>
    </Gather>
    <Say voice="man">Tell me, Mister Anderson, what good is a phone call if you are unable to speak?</Say>
    <Hangup/>

  <!-- The red pill: two voices, a recorded clip, and spoken emphasis -->
  {% elsif Digits == "1" %}
    <Say voice="man">Remember: all I am offering is the truth.</Say>
    <Pause length="1"/>
    <Say voice="woman">Follow the white rabbit.</Say>
    <Play>AUDIO_URL</Play>
    <Say voice="man">Welcome to the real world.</Say>
    <Pause length="1"/>
    <Say voice="woman">There is no <emphasis level="strong">spoon</emphasis>.</Say>
    <Hangup/>

  {% elsif Digits == "2" %}
    <Say voice="man">The story ends. Goodbye.</Say>
    <Hangup/>

  <!-- Any other key: the same line twice, with loop -->
  {% else %}
    <Say voice="man" loop="2">Mister Anderson.</Say>
    <Say voice="man">That was not one of the pills. Goodbye.</Say>
    <Hangup/>
  {% endif %}
</Response>

Step 2: Test it

Call and press 1 to hear both voices, your clip, and the stressed “spoon”. Call again and press 9 to hear the repeated line, or stay silent to hear what Agent Smith thinks of a caller who doesn’t speak.

How the prompts work

The markup that shapes what callers hear
Markup What it does
<Say voice="man">Uses the built-in male voice. woman or no voice gives the female voice. With your own text-to-speech provider, voice takes that provider’s voice names.
<emphasis level="strong">Stresses the words inside it. moderate and reduced are the other levels; any other tag inside a <Say> is read as plain text.
<Say loop="2">Speaks the text twice. loop="0" repeats it until the call ends.
<Pause length="1"/>Leaves a second of silence between lines.
<Play>Plays an audio file. The platform fetches it once and caches it; to replace a clip, give the new file a new URL.

Choosing a language is covered by the multilingual line example.

Where the movie turns up

References to The Matrix in the call flow
Where Reference
The menuMorpheus’s offer of the blue pill and the red pill.
The red pill“Follow the white rabbit,” “Welcome to the real world,” and “There is no spoon.”
No key at allAgent Smith: “What good is a phone call if you’re unable to speak?”
A wrong key“Mister Anderson,” as Agent Smith calls Neo.

Limits of this design

  • Two built-in voices per language. The built-in voices offer one male and one female voice. More voices, or a particular one, need your own text-to-speech provider.
  • Only emphasis is honored. Inside <Say>, <emphasis> is the one tag that changes how text is spoken.
  • The clip must be reachable. If the audio URL can’t be fetched, or serves something other than audio, the clip doesn’t play.

Credits

  • The pills, Morpheus, and Agent Smith come from The Matrix (1999), written and directed by the Wachowskis and distributed by Warner Bros. Keanu Reeves plays Neo, Laurence Fishburne plays Morpheus, Carrie-Anne Moss plays Trinity, and Hugo Weaving plays Agent Smith.
  • The line and its menu are fictional in this example. VoiceTel is not affiliated with the film or its rights holders.
  • References: the text-to-speech guide, the <Say> reference, and the <Play> reference.

Trusted by