{"say":} object

Says something to the user. Unlike "ask", this function has no ability to wait for a response from the user.

On voice / phone sessions:

Say can play text strings using TTS (text to speech) or play URL's as audio files.

The supported sound formats (and their proper file extensions) for the Tropo platform are as follows:

  • 8kHz, 8bit u-law (wav or raw) (*.wav or *.ulaw)
  • 8kHz, 8bit a-law (wav or raw) (*.wav or *.alaw)
  • 8kHz, 8bit pcm (wav) (*.wav)
  • 8khz, 16bit pcm (wav or raw) (*.wav or *.pcm)
  • MS-GSM (wav) (*.wav)
  • GSM 6.10 (raw) (*.gsm)

You can use other formats like MP3, but they will be automatically downsampled and converted due to limitations in telephony standards, so it's always best to have your files in 8bit, 8Khz u-law format from the start.

For more information, review this blog post.

On SMS

Say will send a text string to the user via SMS.

Fields

value
Data Type: 
String
Default: (none) Required

This defines what the user will hear when the verb is executed. In the case of a voice channel, this can be text for the Text to Speech engine or a URL to play an audio file. In the case of a text channel, text is sent to the user via SMS or instant message.

allowSignals
Data Type: 
String or Array
Default: 
* (any signal)
Optional

This parameter allows you to assign a signal to this function. Events from the Tropo REST API with a matching signal name will "interrupt" the function (i.e., stop it from running). If it already ran and completed, your interrupt request will be ignored. If the function has not run yet, the interrupt will be queued until it does run.

By default, allowSignals will accept any signal as valid; if you define allowSignals as "", it defines the function as "uninterruptible". You can also use an array - the function will stop if it receives an interrupt signal matching any of the names in the array.

as
Data Type: 
String
Default: (none) Optional

This specifies the type of data being spoken, so the TTS Engine can interpret it correctly. The possible values are "DATE", "DIGITS" and "NUMBER". Applies to voice only.

name
Data Type: 
String
Default: (none) Required

This is the key used to identify the result of an operation, so you can differentiate between multiple results. As an example, if you asked the user for their favorite color, you could set the name value as 'color' while the returned value might be 'blue'. Not particularly useful if there's only one result returned, but if there are multiple results it helps to determine which result belonged to which operation.

required
Data Type: 
Boolean
Default: 
true
Optional

This determines whether Tropo should move on to the next verb; if required is set to 'true', Tropo will only move on to the next verb if the current operation completely successfully.

voice
Data Type: 
String
Default: 
allison
Optional

Specifies the default voice to be used when speaking text back to a user.

A full list of all voices can be found here (there are many, many options).

Examples

Example showing audio & TTS

{
   "tropo":[
      {
         "say":[
            {
               "value":"Guess what? http://www.phono.com/audio/troporocks.mp3"
            }
         ]
      }
   ]
}

Example as an Object

{
   "tropo":[{"say":{"value":"Please enter your account number..."}}]
}

Example paired with an event trigger

{
   "tropo":[
      {
         "say":[
            {
               "value":"Success!"
            }
         ]
      },
      {
         "on":{
            "next":"document2.json",
            "event":"continue"
         }
      }
   ]
}

Example including SSML

{
    "tropo": [
        {
            "say": [
                {
                    "value": "<?xml version='1.0'?><speak><say-as interpret-as=\"vxml:currency\">USD51.33</say-as></speak>"
                } 
            ] 
        },
        {
            "say": [
                {
                    "value": "<?xml version='1.0'?><speak><say-as interpret-as=\"vxml:digits\">20314253</say-as></speak>"
                } 
            ] 
        },
        {
            "say": [
                {
                    "value": "<?xml version='1.0'?><speak><say-as interpret-as=\"vxml:number\">2031.435</say-as></speak>"
                } 
            ] 
        },
        {
            "say": [
                {
                    "value": "<?xml version='1.0'?><speak><say-as interpret-as=\"vxml:phone\">4075551212</say-as></speak>"
                } 
            ] 
        },
        {
            "say": [
                {
                    "value": "<?xml version='1.0'?><speak><say-as interpret-as=\"vxml:date\">20090226</say-as></speak>"
                } 
            ] 
        },
        {
            "say": [
                {
                    "value": "<?xml version='1.0'?><speak><say-as interpret-as=\"vxml:time\">0515a</say-as></speak>"
                } 
            ] 
        } 
    ]
}