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);
}
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¶
| Signature: | status() => string |
|---|
Returns 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'
}
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.
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.