Tropo WebAPI Development Guide

{"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 / IM sessions:

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

usage

{ "say": {
    "value": String,
    "allowSignals": String or Array,
    "as": String,
    "name": String,
    "required": Boolean,
    "voice": String } }

fields

value	Data Type: String	Default: "" (undefined)	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: "" (undefined)	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: "" (undefined)	Optional
	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's many, many options).

code samples

Example showing audio and 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 showing inclusion of 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>" 
                } 
            ] 
        } 
    ]
}

additional links

none

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page