Hosted Javascript API

Introduction

The Sift API provides a wide array of speech and telephony capabilities that makes it possible to build sophisticated voice applications. However, a large number of asynchronous events – completion of processing, an incoming phone call, live transcripts – necessitate running a server that is always ready to handle messages from the Sift API servers.

For large, permanent applications this may be a minor concern, however for prototypes, experiments, and smaller applications, this is a large overhead. Additionally, you may simply want to create your application quickly without setting up and maintaining a server.

Hosted Scripts are small Javascript programs that run inside a specialized environment where they can interact directly with live communications channels. Hosted Scripts can be entirely written and tested from within the browser, or uploaded using the REST API. Hosted Scripts access Gridspace API function through special library functions that are accessible automatically from any hosted script.

Below we provide reference on the objects and functions that define the Hosted Script Javascript environment. You can also find a wide variety of full example applications in the Hosted Scripts editor at https://api.gridspace.com/scripts/try.

The gs object

The hosted script API defines a global object called gs which contains the following members:

gs.onIncomingCall

Signature:onIncomingCall(connection)

You should set this to a function to handle incoming calls to your script. If set, this function will be invoked every time a new incoming call is received by the Application object associated with the script. Incoming calls may be triggered by a telephone call to a phone number associated with the Application, or by a voip client with an authentication token that is bound to the Application.

The function should take a single argument: a Connection object representing the connection between the caller and the application.

Note

Incoming call messages may not always execute in the same Javascript environment, so your scripts should not assume that two calls will share the same namespace. In particular, global variables changed during one call to the onIncomingCall function may not be preserved during the next onIncomingCall. If your application needs to persist data between calls, use the gs.store function instead.

gs.onIncomingCall = function(connection) {
    connection.say("Thank you for calling");
}

gs.onStart

Signature:onStart()

If the gs.onStart function is defined by a script, it will be executed when the user presses the “Start” button in the Hosted Scripts online editor. This allows you to create scripts that can be started manually, rather than waiting for an incoming call.

Similar to the gs.onIncomingCall function, the global state will not be preserved between calls to gs.onStart.

gs.onStart = function() {
    var connection = gs.createPhoneCall('+15552223333');
    if (connection.status == "connected") {
        connection.say("Hello");
    }
}

gs.email

Signature:email(subject, body, sender, recipients)

Sends an email to the given recipients. sender should be a valid email address, which will appear as the “sender” of the email in the recipient’s mail client. Recipients should be a list of up to 20 email addresses to send to.

gs.email("Subject of email",
         "Thank you for receiving this email.",
         "[email protected]",
         ["[email protected]", "[email protected]"]
    );

gs.post

Signature:post(url [, data, success, dataType, options])

Sends a POST HTTP request to a given URL. URL should be an http or https url accessible from the Internet. data is the content to send in the body of the HTTP request. If dataType is set to “html” (the default), then data should contain only string values and keys. This allows your script to access external resources or APIs.

success is a callback function that will be executed when a successful HTTP response is received.

options is an object that may contain the following keys:

Key Description
auth_mode The authetication method to use. Can be basic or digest. Defaults to basic.
auth_username Username to use during authentication.
auth_password Password to use during authentication.
gs.onIncomingCall = function(connection) {
    if (connection.type == 'phone') {
        gs.post(
            "https://mysite.com/calls",
            {"phoneNumber":connection.fromPhoneNumber},
            function(data) {
                console.log("Response data:", data);
            },
            'http'
        );
    }
}

gs.get

Signature:get(url [, success, options])

Sends a GET HTTP request to a given URL. URL should be an http or https url accessible from the Internet.

success is a callback function that will be executed when a successful HTTP response is received.

options is an object that may contain the following keys:

Key Description
auth_mode The authetication method to use. Can be basic or digest. Defaults to basic.
auth_username Username to use during authentication.
auth_password Password to use during authentication.
gs.onIncomingCall = function(connection) {
    if (connection.type == 'phone') {
        gs.post(
            "https://mysite.com/calls",
            {"phoneNumber":connection.fromPhoneNumber},
            function(data) {
                gs.log("Response data:", data);
            }
        );
    }
}

gs.sms

Signature:sms(phoneNumber, message)

Send an sms message to the given phone. phoneNumber should be an E.164-formatted US phone number (starting with “+1”). Normal text rates apply.

gs.onIncomingCall = function(connection) {
    if (connection.type == 'phone') {
        connection.record(10);
        connection.hangUp();
        gs.sms("+15552223333", "Got a new recording.")
    }
}

gs.store

Signature:function(key, value)

Save a key-value pair to the persistent data store for this application. Since each call may be executed in a separate Javascript context, global variables will not be persisted in between calls. Clients should therefore use this function to store any state that is shared between calls. The key parameter should be a unique string, which can be used to later retrieve the provided value via the _gs-retrieve function. value must be a JSON-serializable object. Scripts are limited to 128 unique keys per script, and each value may be up to 10KB in size.

gs.onIncomingCall = function(connection) {
    var i = gs.retrieve("count") || 0;
    gs.store("count", i + 1);
    connection.say("You are caller number " + i);
}

gs.retrieve

Signature:function(key)

Returns a value that was previously set using gs.store. If the key has never been set, returns null.

Connection object

A Connection object represents a connection between a telephone or voip client and the Gridspace Sift servers. You can use Connection objects to control the behavior of your application, connect endpoints together, send audio, and collect voice data.

Connection.type

type:String

Either “voip” or “phone”, depending on the type of client that is represented by the connection object.

Connection.status

type:String

The current status of the connection. Can be any of the following strings.

Value Description
connected The connection was successfully established, and the endpoint can send and receive audio.
failed We were unable to establish a connection. This usually means the destination did not answer the call.
finished The call used to be connected and completed normally.

Connection.direction

type:String

Either “inbound” or “outbound”. If “inbound”, then this is a connection initiated by an end user, otherwise the call was initiated by Sift to a user’s phone or voip client.

Connection.fromPhoneNumber

type:String

The E.164-formatted phone number of the initiator of the connection. If _js-connection-direction is “inbound”, then this would be the end user’s phone number, otherwise it is the phone number used by your application to call the end user. Only defined if the connection type is “phone”.

Connection.toPhoneNumber

type:String

The E.164-formatted phone number of the recipient of the connection. If _js-connection-direction is “outbound”, then this would be the end user’s phone number. If the direction is “inbound”, then this is the phone number called by the end user. Only defined if the connection type is “phone”.

Connection.say

Signature:say(String text)

Say something over the connection using text to speech software. Takes a single string value representing the text to say over the connection. This function blocks until the computer voice is done speaking.

connection.say("Hello thanks for calling");

Connection.play

Signature:play(url)

Play an audio file over the connection. Takes a single string argument, which should be the http or https URL of the file to play. The file referenced by URL must be either a .wav or .mp3 audio file. Blocks until the file is done playing.

Example

connection.play("https://sounds.com/trumpet_sound.wav");

Connection.getDigits

Signature:getDigits(count [, options]) => string

Waits for the user to press a sequence of count keys on their phone and then returns the result as a string. Optionally plays a sound file or spoken prompt to the user. Options is a dictionary of additonal arguments with the following optional properties:

Property Type Description
promptUrl String Url of a sound file to play while waiting for the user to press digits. Subject to the same restrictions as the url argument to Connection.play.
promptText String Text to say to the connection using text to speech software. If both promptText and promptUrl are provided, the system will try to download and play the audio file first and fall back to speaking only if the download fails.

Example

gs.onIncomingCall = function(connection) {
    var digits = connection.getDigits(4, {promptText: "Please enter the secret code"});
    if (digits == "123#") {
        connection.say("good job");
    }
};

Connection.joinConference

Signature:joinConference(name [, options])

Connect the target connection to a multi-party conference line. The name argument is a unique string name for the conference. If you call joinConference on any connections with the same name, they will be connected to each other in the same conference room. Returns immediately upon connecting to the conference. The options parameter is a dictionary of Conversation options.

Note

The options parameter is ignored when the conference is already in progress. In particular, any callbacks defined will be called at most once per event per active conference. Normally, you will be joining the conference from the same line of code and this is the desired behavior. However, if you have multiple scripts that pass different options to the same conference, be aware that only the first options received for that conference will take effect.

Example

gs.onIncomingCall = function(connection) {
    connection.joinConference("PartyChat", {
        doRecord: true,
        processors: ['findtopics', 'transcribe'],
        onDoneProcessing: function(conversation) {
            // Email myself the trancript.
            gs.email("New conversation about " + conversation.topics,
                     "Transcript: " + conversation.transcript,
                     MY_EMAIL,
                     [MY_EMAIL]);
        }
    });
};

Connection.callPhone

Signature:callPhone(phoneNumber [, options])

Initiate an outbound call to a phone number and connect it to the target connection.

Blocks until the call ends, either due to a timeout or when either party hangs up the call. You may check the status property of the returned Conversation to check if the call was answered or was unable to connect.

The options parameter should be set of key-value pairs to configure the call. All Conversation options are supported, plus one additional option:

Property Type Description
maxRings Integer Number of rings to wait before cancelling the call. In case of timeout, the returned object will have a status of “failed”.

Returns a Conversation object.

Example

gs.onIncomingCall = function(connection) {
    var conversation = connection.callPhone("+15552418762", {
        maxRings: 5,
        doRecord: true,
    });
    if (conversation.status == 'failed') {
        connection.say("Sorry I am not available");
    }
};

Connection.callClient

Signature:callClient(clientName [, options])

Initiate an outbound call to a WebRTC client and connect it to the target connection. See the VOIP Client Reference for details on how to set up a WebRTC client to accept incoming calls. Blocks until the call ends, either due to a timeout or when either party hangs up the call.

clientName is the name of the client to contact. The name should match the one in the token used to initialize a Gridspace web client.

options contains a set of key-value pairs to configure the call. All Conversation options are supported, plus one additional option:

Property Type Description
ringTimeout Number Number of seconds to wait before cancelling the call. In case of timeout, the returned object will have succeeded set to false.

Example

gs.onIncomingCall = function(connection) {
    connection.callClient('client100');
};

Connection.record

Signature:record(maxSeconds [, options])

Records the connection audio for a given period of time. Blocks until recording is maxSeconds long, or the user hangs up.

maxSeconds is the number of seconds to record the end user’s voice.

options is a set of key-value pairs to configure the call. All Conversation options are supported, except doRecord which is assumed to be true.

Example

gs.onIncomingCall = function(connection) {
    connection.say("Please leave a message");
    connection.record(60, {
        processors: ['transcribe']
    });
};

Connection.enqueue

Signature:enqueue(queueName [, options])

Puts the connection on hold and adds it to a queue. The connection will wait in the queue until either the end user hangs up, or it reaches the front of the queue and another connection calls Connection.dequeue with the same queue name.

You may specify either the URL of a sound file to play to the connection while on hold, or a holdRoutine function that can interact with the connection. The holdRoutine can use any of the connection functions, including joining other conversations or enqueuing onto other queues. The connection may only be in a single queue at a time, so if enqueue is called in the holdRoutine, it is removed from the previous queue.

options is a javascript object with any of the following attributes.

Property Type Description
holdMusic String URL of a .wav or .mp3 file to be played while the user waits.
holdRoutine Function A function that takes a connection object as a parameter. The function will be executed until the connection is dequeued, at which point any function call on the connection will raise an exception, indicating that the holdRoutine is done. Only one of holdRoutine or holdMusic should be specified.

Example

gs.onIncomingCall = function(connection) {
    connection.enqueue('Support', {
        holdRoutine: function(connection) {
            // This function will be run until the function returns
            // or the connection is pulled from the queue.
            while (true) {
                connection.play("http://mysite.com/song.wav");
                connection.say("Please continue to hold");
            }
        }
    });
}

Connection.dequeue

Signature:dequeue(queueName [, options])

Pull a connection from the front of the queue named queueName and place it in a new Conversation with the target connection. Connections are added to the queue with the Connection.enqueue command. If the queue is empty, the connection will wait until another connection is enqueued, or the caller may specify a maximum wait time. Blocks until the conversation ends due to either party disconnecting, or timeoutSeconds expire with no connection joining the queue.

options contains a set of key-value pairs to configure the conversation. All Conversation options are supported, plus one additional option:

Property Type Description
timeoutSeconds Number If the queue is empty, the number of seconds to wait for a client to be enqueued before returning.

Example

gs.onIncomingCall = function(connection) {
    connection.dequeue('Support', {
        onStarted: function(conversation) {
            console.log("Started conversation:", conversation.id);
        },
        timeoutSeconds: 45,
    });
};

Connection.getFreeResponse

Signature:getFreeResponse([options]) => string

Collects a voice response from the user and returns their speech as a text string. The function will block until a pause in speech is detected, or until an optionally provided timeout is exceeded.

options is an optional Voice response options object.

Accuracy Tip

Choosing from a list of available responses is generally an easier task for machines than transcribing free-form speech, so it is a good idea to use GetMultipleChoice or one of the restricted response commands whenever possible. This will minimize the chance that we mishear what the user said.

Example

gs.onIncomingCall = function(connection) {
    var favoriteFood = connection.getFreeResponse({
        promptText: "What is your favorite food?",
        timeoutSeconds: 15
    });
    gs.post('https://mysite.com/favoritefoods',
        {
            'food': favoritefood,
            'caller': connection.fromPhoneNumber
        }
    );
};

Connection.getNumber

Signature:function([options]) => string

Get a spoken numeric response from the user. Will play an optional prompt from a sound file and then interpret the natural language response from the user as a numeric value.

Accepts non-negative integers or sequences of digits, eg. “forty four” and “four four” will both be parsed as “44”.

options is an optional Voice response options object.

Returns a string of base-10 digits, or null if the user did not say a valid numeric value.

Note

The value property is provided as a string instead of an integer to allow the user to say sequences of digits as well as natural numbers. This allows results like “0000”, when the user said “zero zero zero zero”, which cannot be accurately represented as an integer. You may wish to the parseInt javascript function if you are only expecting a number.

Warning

English can be ambigious when describing sequences of large numbers. For instance, if a user says “two thousand five hundred”, this could be interpreted as a single number (2500) or two numbers (2000 and 500). The GetNumber command will interpret phrases as a single number whenever it makes sense to do so. In the above example, the result field would contain the string “2500”. To avoid ambiguous responses, never ask the end user for multiple numbers larger than 100 in a single prompt.

Example

gs.onIncomingCall = function(connection) {
    var response = connection.getNumber({
        promptText: "How many wigits would you like to order?",
        timeoutSeconds: 10
    });
    if (response) {
        var count = parseInt(response);
        var confirmed = connection.getYesOrNo({
            promptText: "Shall I order " + count + " wigits?"
        });
        if (confirmed) {
            gs.post("https://mysite.com/order", {
                count: count,
                caller: connection.fromPhoneNumber
            });
        }
    }
}

Connection.getYesOrNo

Signature:function([options]) => boolean

Get a spoken yes or no response.

options is a plain object containing Voice response options attributes.

Returns a boolean value representing an affermative or negative response, or null if the user did not say a synonym for either “yes” or “no”.

Example

gs.onIncomingCall = function(connection) {
    var response = connection.getYesOrNo({
        promptText: "Would you like to be connected to a representative?"
    });
    // Response will be either true, false, or null. Careful here: remember that
    // "null" and "false" are both falsy but have different meanings.
    if (response === true) {
        connection.enqueue('support');
    }
}

Connection.getMultipleChoice

Signature:function(choices [, options]) => string

Get a spoken response from a fixed set of possible values. The function will block until a pause in speech is detected, or until the optionally provided timeout is exceeded.

choices is a list of accepted response strings.

options is a plain object containing Voice response options attributes.

Returns a string from from choices if the user says exactly one of the possible choices, or null if the timeout expires, or the user says something outside the list of choices.

Example

gs.onIncomingCall = function(connection) {
    var choices = ["fraud", "insurance", "credit cards"];
    var choice = null;
    while (!choice) {
        choice = connection.getMultipleChoice({
            promptText: "which department are you trying to reach?",
            timeoutSeconds: 30
        });
        if (!choice) {
            connection.say("Options are " + choices.join(" "));
        }
    }
    // Function defined elsewhere to connect to a department by name...
    callDepartment(connection, choice);
}

Connection.getMultipleChoiceOrDigits

Signature:function(choices, digitCount [, options]) => object

Similar to Connection.getMultipleChoice but allows the end user to say a response or press a sequence of digits on the phone keypad instead. Blocks until the user enters digitCount digits, or starts speaking and then pauses, or the optional timeout is exceeded.

choices is a list of accepted response strings.

digitCount is a number of digits to collect from the user before returning.

options is a plain object containing Voice response options attributes.

Returns an object with the following attributes:

Property Type Description
digits string A string of length digitCount containing the digits pressed by the user in the same format as returned by Connection.getDigits. Is null if the did not enter digitCount digits.
choice string One of choices if the user said an exact match or null otherwise.

At least one of the above attributes will always be null. If the user fails to respond or press the required number of digits, then both attributes will be null.

Example

gs.onIncomingCall = function(connection) {
    var choices = ["fraud", "insurance", "credit cards"];
    var extensions = {
        "00": "fraud",
        "01": "insurance",
        "02": "credit cards"
    };
    var choice = null;
    while (!choice) {
        var result = connection.getMultipleChoiceOrDigits(choices, 2, {
            promptText: "Say the name of the department you wish to reach or enter \
                         your party's extension on the keypad",
            timeoutSeconds: 30
        });
        if (result.digits) {
            // Choice will be undefined if no such extension.
            choice = extensions[result.digits];
        }
        else if (result.choice) {
            choice = result.choice;
        } else {
            connection.say("Options are " + choices.join(" "));
        }
    }
    // Function defined elsewhere to connect to a department by name...
    callDepartment(connection, choice);

Connection.getDate

Signature:getDate([options]) => string

Get a spoken natural language response from the end user and interpret it as a date. The function will block until a pause in speech is detected, or until the optionally provided timeout is exceeded.

options is a plain object containing Voice response options attributes.

Returns the date that was spoken, as an ISO 8601-formatted date string. If the user does not specify a year, the year portion of the date string is omitted. Returns null if the optional timeout is exceeded or the user does not say a valid date.

Example

gs.onIncomingCall = function(connection) {
    var date = connection.getDate({
        promptText: "on what date do you want to schedule your appointment?"
    });
    if (date) {
        gs.email("new appointment", "Date: " + date, MY_EMAIL, [MY_EMAIL]);
    }
}

Connection.getScannedResponse

Signature:getScannedResponse(query [, options]) => object

Use a Scanner Query Language string to parse a natural language response from the user.

query is a string in Scanner Query Language defining the expected response structure.

options is a plain object containing Voice response options attributes.

If the response given by the user matches the query argument, this returns a Scanner result object object, otherwise it returns null. You can use this function to parse complex spoken responses from the user while being roubust to variations in phrasing. For full details, see Parsing Language With Scanners.

Example

var query = "~~~'{date}' and ~~~'{time}'";
var result = connection.getScannedResponse(query, {
    promptText: "Say the date and time of your reservation"
});
if (result) {
    date = result.extractions[0].value;
    // date has a date string like '05-21-1988'
    time = result.extractions[1].value;
    // time has a time string like '14:25'
}

Connection.hangUp

Signature:hangUp()

Terminate the connection.

Example

gs.onIncomingCall = function(connection) {
    connection.say("Please leave a message");
    connection.record(60);
    connection.hangUp();
}

Voice response options

All connection functions that wait for a voice response from the user take an optional Options parameter, which is a plain javascript Object with any of the following attributes defined.

promptUrl

type:String

Url of a sound file to play to the user as soon as the system starts listening for a voice response. The user may start talking while the sound is still playing.

promptText

type:String

Text to say to the user with text to speech software as soon as the system starts listening for a voice response. The user may start talking while the system is still speaking.

timeoutSeconds

type:Number

Time in seconds to wait for the user to start speaking. If the user is silent, the function returns a null result.

Conversation options

The Connection.joinConference, Connection.callPhone, and Connection.callClient functions all create Conversations. In the Gridspace API, a Conversation represents a spoken interaction between one or more parties. Conversations can be processed and analyzed in many ways both while the conversation is taking place, and after the conversation ends. All conversation-generating functions take an optional Conversation Options argument, which is a plain Object with any of the following attributes.

onTranscript

Signature:onTranscript(transcript, conversation)

Callback function that is called during the conversation whenever a line of dialog is transcribed.

transcript is a js-transcriptobject with the transcribed text and metadata.

conversation is a Conversation object object for the conversation being transcribed.

Example

connection.joinConference("C1", {
    onTranscript: function(transcript, conversation) {
        gs.log(transcript);
    }
 });

onTopics

Signature:onTopics(topics, conversation)

Callback function. Called during the conversation when a set of conversation topics is detected.

topics is a list of strings, each representing a recent topic mentioned in the Conversation.

conversation is a Conversation object object for the conversation being transcribed.

Example

connection.joinConference("C1", {
    onTopics: function(topics, conversation) {
        if ('music' in topics) {
            conversation.playToAll('http://mysite.com/song.mp3')
        }
    }
 });

onDoneProcessing

Signature:onDoneProcessing(conversation)

Callback function. Called when the conversation ends and all processors have completed. Depending on which processors you specify in the processors command and how long the conversation is, it may take up to a few hours after the conversation ends before this function is called.

conversation is a Conversation object object in the “finished” state.

Example

connection.joinConference("C1", {
    doRecord: true,
    processors: ['transcribe', 'classify:severity'],
    onDoneProcessing: function(conversation) {
        gs.email("Transcript", conversation.transcript, MY_EMAIL, [MY_EMAIL]);
    }
 });

onScan

Signature:onScan(queryResults, conversation)

Callback function. Called when one or more of the queries passed via the scanQueries parameter matches a spoken phrase.

Example

connection.joinConference("C1", {
    scanQueries: ["~~'hello my name is {name}'"],
    onScan: function(scan, conversation) {
        var match = scan[0][0];
        var name = match['extractions'][0];
        console.log("name: ", name);
    }
});

doRecord

type:Boolean

If true, recording will be enabled for the conversation. A separate audio recording will be generated for each speaker in the conversation with only their voice, as well as a merged audio file with all speakers.

processors

type:List[String]

A list of Conversation Processors to run when the conversation ends. doRecord must be true to run processors.

scanQueries

type:List[String]

A list of query strings to look for during the conversation. If something is said that matches one of the queries, the onScan callback function is called. Query strings must be in Scanner Query Language format. See Parsing Language With Scanners for more information on how to structure queries.

Example

connection.joinConference("C1", {
    scanQueries: ["~~'hello my name is {name}'"],
    onScan: function(scan, conversation) {
        var match = scan[0][0];
        var name = match['extractions'][0];
        console.log("name: ", name);
    }
});

Conversation object

A Conversation represents an instance of one or more active connections communicating together. Conversations are created by the Connection.record, Connection.callPhone, Connection.joinConference, and Connection.dequeue commands.

If a Conversation has audio data available, it may be analyzed in various ways using Conversation Processors.

id

type:String

Unique identifier for the Conversation.

status

type:String

The following strings are possible values of the status attribute of a Conversation.

Status Description
in-progress The conversation is in progress.
processing The conversation has ended and the Conversation Processors bound to the conversation are still working.
finished The conversation has ended and all previously bound Conversation Processors are done working. Note if more processors are bound to the conversation, its status may return to processing.

channels

type:List[Object]

A list of connections in a conversation, their metadata, and, possibly, audio. Each object in the list has the following properties. Present only if the conversation is in the “finished” state.

Property Type Description
start_ms integer The time at which this connection joined the conference, measured in milliseconds from start_time.
end_ms integer The time at which this connection left the conference, measured in milliseconds from start_time.
audio object A recording of a single device in a conversation, if available.
audio.wave_file string A URL of a PCM wave recording of the channel.
audio.duration_ms integer The duration of the recording in milliseconds.
audio.snr float The signal to noise ratio of the recording. A measure of quality. Higher is better.
audio.rt60 float The reverberation time of the recording. A measure of quality. Normally, lower is better.
connection object The connection object associated with this channel.

topics

type:List[String]

A list of topics discussed in the conversation. Present only if the conversation is in the “finished” state, AND “findtopics” was in the list of Conversation Processors provided in the conversation options.

transcript

type:List[Object]

Full transcript of the entire conversation. Present only if the conversation is in the “finished” state AND “transcribe” was in the list of Conversation Processors provided in the conversation options. Provided as a chronologically ordered list of segments, each attributed to a single speaker. Each item in the list has the following properties.

Property Type Description
connection_id string The ID of the connection that said this line of the transcript.
offset_ms integer Time in milliseconds from the start of the conversation that the current segment was spoken.
duration_ms integer Duration in milliseconds of the current segment of the transcript.
text string Text transcript of the voice segment.

playToAll

Signature:playToAll(url)

Play a file located at url to the participants in an active conversation. Only works if the status property is “in-progress”, otherwise does nothing. The file referenced by URL must be either a .wav or .mp3 audio file. Blocks until the file is done playing.

gs.onIncomingCall = function(connection) {
    connection.callPhone('+15552221111', {
        onStarted: function(conversation) {
            conversation.playToAll('http://mysite.com/sounds/call_started.wav');
        }
    });
};

Scanner result object

When a scanner is run on speech, a Scanner result object is returned for each match in the text. It contains the text of the match, and any extracted values. For instance, the query ~"{number} years old" might produce the following scanner result object:

{
    extractions: {
        0: '35',
    },
    match: "thirty five years old"
}

extractions

type:Object

Gives the values associated with each extractor in the query. All extracted values are keyed off of their index number, which is determined by their order in the original query. For example, the result for the query '{name}' or '{phoneNumber}' will store the name at index 0 and the phone number at index 1. For queries with an “or” operation, the scanner may not return values for each extractor. In this case null will be stored for any missing indices.

If you have a labeled extractor in your query, for instance '{number:age}', the extracted value will be also be stored under the given label. In this example, we could access the age with result.extractions['age'] or result.extractions[0].

match

type:String

A string containing the portion of the original text which matched the query. This may not be exactly equal to the query string due to fuzzy matching or extractors.