Call Us Today! 877.742.2583




Page tree
Skip to end of metadata
Go to start of metadata

About

This page provides the documentation of the Javascript FreeSWITCH API.

Docs Help Needed

Most API aren't documented, so please feel free to improve the documentation and complete the API examples.

This page is in process, having been copied from Lua (for consistent formatting).

The JavaScript engine has changed from Spidermonkey to V8. Verification of the APIs (as seen in the old wiki) is needed.

 Click here to expand Table of Contents

 

FreeSWITCH DB Access From JavaScript

FreeSWITCH uses SQLite for a variety of internal operations. There is a mechanism where you can also use SQLite in your JavaScript applications. The methods and properties available are listed below in alphabetical order.

SQLite is provided to demonstrate the capabilities of FreeSWITCH. For production systems processing high volumes of calls a database system that can handle that volume must be used, for example Postgres.

 

apiExecute

SPIDERMONKEY V8 UNVERIFIED

Executes an API (FreeSWITCH console) command.
(To execute a dialplan application, use session.execute.)

For a list of commands that can be executed with apiExecute, see the Command reference.

Usage:

apiExecute(apiCommand, args);
  • apiCommand (String) - the command name to execute
  • args (String) - arguments for the command (all joined together into a single string) (not the internal arguments variable)

Returns: undefined ?

apiExecute examples
// ???
apiExecute("show", "channels");

//Plays a sound file for everyone currently residing in conference room 1.
apiExecute("conference", "1 play /usr/local/freeswitch/sounds/myfile.wav");

//Using text to speech engine speaks to everyone in conference room 1.
apiExecute("conference", "1 say Hello there");

apiExecute Notes

apiExecute() does not have the same object hierarchy as other methods exposed via mod_spidermonkey (it is not an extension of session).

 

api (console cli) commands can be executed via a workaround. The following will set myvar with the output of apicommand()
execute("set","myvar=${apicommand()}")

 

 

bridge

SPIDERMONKEY V8 UNVERIFIED

Bridges 2 channels together.

bridge usage
bridge(session1, session2[, callback[, callbackArgs])
  • session1 (Session) - one session to bridge
  • session2 (Session) - the other session to bridge
  • callback (Function) - function to call every time DTMF is generated on either of the channels
  • callbackArgs (String) - data that you wish to access in the callback

Returns: undefined ?

callback

The callback function argument is invoked every time DTMF is generated on either one of the session channels.

callback example
function <callbackName> ( session, type, dtmf, userData  ) {
   //.. do something ..
   return <value>; 
}

Arguments:

  • session (string) - the session UUID that generated the event.
  • type (object)  - the type of event object (list/link possible values here)
  • dtmf (object)
    • dtmf.digit (string) - digit pressed
    • dtmf.duration (Number?) - duration the digit was pressed.
  • userData (Mixed) - the callbackArgs passed to the callback from the bridge function

Returns:

The meaning of the return value varies depending on the current telephony operation.

Recording

  • true - keep recording
  • false - stop
  • "pause"
  • "restart"

Playing Back

  • true - keep going, do not interrupt the current operation
  • false - stop, and exit the current operation
  • "seek:[+/-][value]" in milliseconds
  • "speed:[+/-][value]" in some unknown unit

    Relative:

    • return("speed:+");

    • return("speed:-");

    • return("speed:+5");

    • return("speed:-5"); 

      Absolute:

    • return("speed:0");

    • return("speed:5");

  • "pause" (toggle; sending a second pause will resume playback)
  • "restart"

Bridge

  • false - stop and exit the current bridge.
  • true - keep going, do not interrupt the current bridge.

Other

  • true - keep going, do not interrupt the current operation
  • false - stop, and exit the current operation

Callback Examples

Simple bridge example
var anotherSession = new Session(session, "sofia/sip/1234@10.10.2.55");
bridge(session, anotherSession);
anotherSession.hangup();

 

This example will print "Given userData.param of under the rock" in the FS console and will recall mycall@mydomain.com every time someone presses a key on either of the call legs

bridge example 2
function logAndStopBridge ( session, type, dtmf, userData) {
 console_log("WARNING","Given userData.param of "+(userData && userData.param));
 return false;
}
session.answer();
while ( session.ready() ) {
  var mySession = new Session("sofia/sip/mycall@mydomain.com");
  bridge(session, mySession, logAndStopBridge, {param:"under the rock"});
} 

console_log

SPIDERMONKEY V8 UNVERIFIED

Logs a message to the console logger.

bridge usage
console_log([level,] message)
  • level (String) - severity of the message ("DEBUG", "INFO", "NOTICE", "WARNING", "ERR", "CRIT", "ALERT"), defaults to "DEBUG" when unspecified
  • message (String) - message to appear in the FS console, usually ends with a newline (\n)

Returns: undefined ?

console_log example
console_log("Hello there\n"); // DEBUG level in FS console
console_log("WARNING", "Ho!\n"); 

 

Database Access

DB.close

This method closes your database connection. Please note that as soon as a script finishes executing the engine will automatically close any CoreDB resources. This close method was designed to help you free up those resources for longer running scripts.

Usage:

DB.close()

 

DB.close example
use("CoreDB");

var DB = new CoreDB("js");
var sql="select * from users;";
DB.prepare(sql);
while(DB.next()) {
   hash = DB.fetch();
   console_log("name = " + hash["name"] + " number " + hash["did"] + "\n");
}
DB.close();
//Do Some other stuff here. 

 

DB.exec

Executes an SQL statement. If you are doing a select you may want to look at DB.prepare instead.

Usage:

exec(sql statement)

 

DB.close example
use("CoreDB");

var db = new CoreDB("js");
var sql="delete from users";
db.exec(sql);

 

DB.fetch

Gets the next row from a select operation.

Usage:

fetch()

 

DB.fetch example
use("CoreDB");

var db = new CoreDB("js");
var sql="select * from users;";
db.prepare(sql);
while(db.next()) {
  hash = db.fetch();
  console_log("name = " + hash["name"] + " number " + hash["did"] + "\n");
}

 

DB.next

This goes to the next row, presumably after you have DB.fetch()ed it.

Usage:

next()
DB.next example
use("CoreDB");

var db = new CoreDB("js");
var sql="select * from users;";
db.prepare(sql);
while(db.next()) {
   hash = db.fetch();
   console_log("name = " + hash["name"] + " number " + hash["did"] + "\n");
}

 

DB.path

Returns the path for the SQLite database.

Usage:

console_log(DB.path + "\n");

DB.prepare

Prepares the specified SQL statement for use.

Usage:

prepare(statement)

 

DB.prepare example
use("CoreDB");

var db = new CoreDB("js");
var sql="select * from users;";
db.prepare(sql);
while(db.next()) {
   hash = db.fetch();
   console_log("name = " + hash["name"] + " number " + hash["did"] + "\n");
}


email

Sends an email from within your application

Usage:

email(to, from, headers, body, [<filename>]);

Arguments:

  • from - from email address
  • to - to email address
  • headers - optional headers (i.e. "Subject: yadayada")
  • body - body of email message
  • filename - optional filename to attach

 

email example
if (eMailTo != "") {
  var tmp_eMailSubject = eMailSubject + sv_caller_id_name + " (" + sv_caller_id_num + ")";
  email(eMailTo, eMailFrom, "Subject: " + tmp_eMailSubject, eMailBody, tmp_Filename);
}

Url Access

FetchUrl

Usage:

var result = fetchUrl(<url>, [bufferSize]);

Arguments:

  • result - Will contain document info, or false if an error occurred during the fetching.
  • url - The complete url to the document.
  • bufferSize - Optional parameter that specifies size of the buffer, default size is 65535 bytes.

Error reasons

  • The url is incorrect.
  • The buffer is too small for the document.

Use through web proxy

If you have to use fetchUrl through a corporate web proxy you can set the environment variable http_proxy='http://proxy_username:proxy_password@proxy.ip.address:proxy.port' You can done this only if security is not a first concern for you (e.g. you are the only one using the freeswitch machine).

Example

var result = fetchUrl("https://localhost/user/get/1");
if (result == false)
  console_log("Failed to get user");
else
  console_log("User doc: " + result);

FetchUrlFile

Fetches the content of a webpage and stores it into a file. This is safer than fetching directly into memory directly since you may not know how much memory it will take until after the page has loaded.
Usage:
fetchUrlFile(url,file)

Arguments

  • url - any cURL supported URL.
  • file - the file including path into which to store the response.
fetchUrlFile("http://www.somewhere.tld/somepage.html","/tmp/somepage.html");

FetchUrlHash

Fetch the response from a webserver and store it in a hash.

Usage:

fetchUrlHash(url,hash)
  • url - any CURL supported format (you can encode data you want to send to the server)
  • hash - name of the hash to save data into

Note: the hash variable name must be enclosed between quotes.

The web server must return data with a

 Content-type: text/plain\n\n

header and attribute=value pairs in the body, e.g.:

 moo=ojnk
foo=bar

Spaces on either side of the name or value will be trimmed off, so 'foo = bar' is valid and in Javascript would be the same as 'foo=bar'

You may have to escape any quoted parameters ( " ) with \" (backslash quote) to get it to work properly due to the way this is converted into Javascript. e.g.

 foo=\"bar\"

FetchURLHash example
var myhash = new Array(); // must be defined in the same scope, i.e. same function
fetchUrlHash("http://www.somewhere.tld/somepage.html","myhash");
for (key in myhash) {
    console_log(key + ": " + myhash[key] + "\n");
}


Security Warning

The data returned is processed with eval(), which means that if the web server has control to send anything it wants the returned data will be processed and can overwrite other variables, execute arbitrary code, whatever. An example might be:

foo=bar";console_log("pwned\n");var blah="

the last var blah=" is to catch the trailing quote and not have a parse error.

Do not fetch arbitrary URLs off the internet with this, only use sites that you control to avoid an evil user from causing harm.


fileDelete

Deletes a file from the system.

Usage:

fileDelete(filename);

Argument:

  • filename - full path to filename (use unix slash "/" even on win32)

Returns:

  • true - on success
  • false - on file not found or failure

 

fileDelete example
rtn = fileDelete("/tmp/recording.wav");

 

File

File.canAppend

Returns a boolean indicating whether or not we can append to the specified file.

Usage:

canAppend

 

File.canAppend example
var fd = new File("/tmp/blah");
fd.open("write,append");
if (fd.canAppend) {
  console_log(fd.name) + "can be appended to\n");
} else {
  console_log(fd.name) + "cannot be append to\n");
}

File.canRead

Returns a boolean indicating whether or not we can read this file.

Usage:

canRead


File.canRead example
var fd = new File("/tmp/blah");
if (fd.canRead) {
  console_log((fd.name) + "can be read\n");
} else {
  console_log((fd.name) + "can not be read\n");
}

File.canReplace

Returns a boolean indicating whether or not we can replace the contents in this file.

Usage:

canReplace


File.canReplace example
var fd = new File("/tmp/blah");
fd.open("read,write,replace");
if (fd.canReplace) {
  console_log(fd.name) + "can be overwritten\n");
} else {
  console_log(fd.name) + "cannot be overwritten\n");
}


File.canWrite

Returns a boolean indicating whether or not we can write to the file.

Usage:

canWrite

 

File.canWrite example
var fd = new File("/tmp/blah");
if (fd.canWrite) {
  console_log(fd.name) + "can be written to\n");
} else {
  console_log(fd.name) + "can not be written to\n");
}

 

File.close

Closes an open file handle.

Usage:

close()


File.close example
var fd = new File("/tmp/blah");
fd.((FreeSwitch Javascript File open|open))("read");
fd.close();


File.copyTo

Copy a file to a new file.

Usage:

copyTo(dest)

 

File.copyTo example
var fd = new File("/tmp/blah");
fd.copyTo("/tmp/moo");

 

File.creationTime

The timestamp of when the file was created.

Usage:

creationTime

 

File.creationTime example
var fd = new File("/tmp/blah");
console_log(fd.creationTime+"\n");

File.error

A File object for standard error.

Usage:

error

 

File.error example
var fd = File.error
fd.open("write");
fd.writeln("\n\ntesting\n\n");

 

File.exists

Returns a boolean indicating whether the file exists or not.

Usage:

exists

 

File.exists example
var fd = new File("/tmp/blah");
if (fd.exists) {
  console_log((fd.name) + "exists\n");
} else {
  console_log((fd.name) + "does not exist\n");
}

 

File.flush

Flushes the buffer to the file.

Usage:

flush()

 

File.flush example
var fd = new File("/tmp/blah");
fd.open("write");
fd.write("hi");
fd.flush();

 

File.hasAutoFlush

Returns a boolean indicating whether or not this file has automatic buffer flushing enabled.

Usage:

hasAutoFlush

 

File.hasAutoFlush example
var fd = new File("/tmp/blah");
fd.open("read,write,autoFlush");
console_log("Do we have auto flush? " + fd.hasAutoFlush + "\n");

 

File.hasRandomAccess

Returns a boolean indicating whether we have random access to this file or not, i.e. will (FreeSWITCH JavaScript File seek|seek) work.

Usage:

hasRandomAccess

 

File.hasRandomAccess example
var fd = new File("/tmp/blah");
fd.open("read");
console_log("Do we have random access? " + fd.hasRandomAccess+"\n"); 

File.input

A file object for standard input.

Usage:

input

 

File.input example
var fd = File.input
fd.open("read");
fd.readln();var fd = File.input
fd.open("read");
fd.readln();

File.isDirectory

Returns a boolean indicating whether or not the current file is a directory.

Usage:

isDirectory

 

File.isDirectory example
var fd = new File("/tmp/blah");
if (fd.isDirectory) {
  console_log(fd.name) + "is a directory\n");
} else {
  console_log(fd.name) + "is not a directory\n");
} 

File.isFile

Returns a boolean indicating whether or this resource is a file.

Usage:

isFile

 

File.isFile example
var fd = new File("/tmp/blah");
if (fd.isFile) {
 console_log(fd.name) + "is a file\n");
} else {
  console_log(fd.name) + "is not a file\n");
} 

File.isNative

Returns a boolean indicating whether or not we are using an OS specific FILE handle.

Usage:

isNative


File.isNative example
var fd = new File("/dev/zero"); // or COM1 or whatever in windows
console_log(fd.isNative);
fd.close();


File.isOpen

Returns a boolean indicating whether or not the file is open.

Usage:

isOpen

 

File.isOpen example
var fd = new File("/tmp/blah");
console_log("Is the file open? " + fd.isOpen + "\n");
fd.open("read");
console_log("Is the file open? " + fd.isOpen + "\n");
fd.close(); 

 

File.lastModified

The timestamp of when the file was last modified.

Usage:

lastModified

 

File.lastModified example
var fd = new File("/tmp/blah");
console_log(fd.lastModified+"\n");

 

File.length

Returns the length of the file.

Usage:

length

 

File.length example
var fd = new File("/tmp/blah");
console_log(fd.length+"\n"); 

 

File.list

Returns the file names in a directory.

Usage:

list()

 

File.list example
var fd = new File("/tmp");
console_log(fd.list()); 

 

File.mkdir

Create a directory in the current directory and point the file object to it.

Usage:

mkdir(directory)

 

File.mkdir example
var fd = new File("/tmp")
fd.mkdir("blah");

 

File.mode

A comma separated list of the modes that you are allowed to use for this file.

Usage:

mode

Modes:

mode - a comma separated list of the file modes

  • read - open for reading
  • write - open for writing
  • readWrite - open for reading and writing
  • append - add to the end of a file
  • create - create the file if it doesnt exist
  • replace - replace the contents with new ones (truncate)
  • autoflush - auto flush the buffer when writing

 

File.mode example
var fd = new File("/tmp/blah");
fd.open("read,append");
console_log(fd.mode+"\n");

 

File.name

Returns the name of the current file without the directory part, the basename.

Usage:

name


var fd = new File("/tmp/blah");
console_log(fd.name);


File.open

Opens a file handle.

Usage:

open(mode)

where mode - a comma separated list of the file modes

  • read - open for reading
  • write - open for writing
  • readWrite - open for reading and writing
  • append - add to the end of a file
  • create - create the file if it doesnt exist
  • replace - replace the contents with new ones (truncate)
  • autoflush - auto flush the buffer when writing
File.open example
var fd = new File("/tmp/blah");
fd.open("read,write,create");

// Read output from an application
var fd = new File("|ls /home");
fd.open("read");
var result = fd.read("128");


File.output

A file object for standard output.

Usage:

output


File.open example
var fd = File.output
fd.open("write");
fd.writeln("\n\ntesting\n\n");

 

File.parent

Returns the parent part of the path.

Usage:

parent

 

File.parent example
var fd = new File("/tmp/blah");
console_log(fd.parent);

File.path

Returns the full path to the current file descriptor.

Usage:

path


File.path example
var fd = new File("/tmp/blah");
console_log(fd.path); 


File.position

The current position in the file.

Usage:

position

 

File.position example
var fd = new File("/tmp/blah");
fd.open("read");
fd.seek(10);
console_log("We are at offset " + fd.position + "\n");
fd.close()

File.read

Reads a specified number of bytes into a buffer.

Usage:

read(size)

size - the number of bytes to read

File.read example
var fd = new File("/tmp/blah");
var buff = fd.read(10);

 

File.readAll

Reads the entire contents of a file into a buffer. 

Be careful of memory allocation with this command so you don't have 1000 calls all trying to read in a 100MB file.

 

Usage:
readAll()


File.readAll example
var fd = new File("/tmp/blah");
var buff = fd.readAll();


File.readln

Reads a file up to a newline into a buffer.

Usage:

readln()

 

File.readln example
var fd = new File("/tmp/blah");
var buff = fd.readln();

File.remove

Deletes a file.

Usage:

remove();

 

File.remove example
var fd = new File("/tmp/blah");
fd.remove();

 

File.renameTo

Renames a file name to some other name.

Usage:

renameTo(newName)

newName - the new name of the file

File.renameTo example
var fd = new File("/tmp/blah");
fd.renameTo("/tmp/moo"); 

 

File.seek

Sets the file pointer to a specified position in a file.

Usage:

seek(offset)

offset - the byte offset to seek to

File.seek example
var fd = new File("/tmp/blah");
fd.open("read");
fd.seek(1024);

 

File.size

Return the file size. This appears to be the same as (FreeSWITCH JavaScript File length)

Usage:

size

 

File.size example
var fd = new File("/tmp/blah");
console_log(fd.size+"\n"); 

 

File.toString

Returns a string for the path to the file.

Usage:

toString()

 

File.toString example
console_log(fd.toString());

 

File.toURL

Returns a URL–formatted object for the file name/path.

Usage:

toURL()

 

console_log(fd.toURL() + "\n");

File.type

Returns the type (i.e. text, UTF, Unicode, etc.) of the file.

Usage:

type

 

File.type example
var fd = new File("/tmp/blah");
fd.open("read");
console_log(fd.type+"\n");

 

File.write

Writes a string to a file.

Usage:

write(string)

 

File.write example
var fd = new File("/tmp/blah");
fd.write("whee!\n");

 

File.writeAll

Writes an array to a file.

Usage:

writeAll(data)

 

File.writeAll example
var data = new Array("moo","ojnk");
var fd = new File("/tmp/blah");
fd.open("write");
fd.writeAll(data); 

 

File.writeln

Writes a string and appends a \n (newline) to the end into a file.

Usage:

writeln(string)

 

File.writeln example
var fd = new File("/tmp/blah");
fd.writeln("this is a test!"); 

 

FileIO

Description

The FileIO object lets you manipulate files.

Synopsis

FileIO(filename,flags)

  • name - the filename including path to open
  • flags are one of
    • r - read
    • w - write
    • c - create
    • a - append
    • t - truncate
    • b - binary

Note: if the file does not exist and the 'c' flag is not set the JS script will abort and an error event will be generated saying it cant open the file.

Example

fd = new FileIO(argv[[0], "r");

Methods

Properties

FileIO.data

Returns the data from a previous read.

Usage:

data()

 

FileIO.data example
fd = new FileIO("/tmp/blah","r");
fd.read(2048);
console_log(fd.data() + "\n"); 

FileIO.path

Contains the path to the current file.

Usage:

path

 

FileIO.path example
fd = new FileIO("/tmp/blah","rc");
console_log(fd.path + "\n"); 

FileIO.read

Reads data from a file.

Usage:

read(size)

 

FileIO.read example
fd = new FileIO("/tmp/blah","r");
fd.read(2048);
console_log(fd.data()); 

FileIO.write

Writes data to a file.

Usage:

write(data)

 

FileIO.write example
fd = new FileIO("/tmp/blah","wc");
fd.write("testing\n"); 

 

getGlobalVariable

SPIDERMONKEY V8 UNVERIFIED

Global variables can be used to share information between all channels. You can save anything in a global variable.

This is not to be confused with a property of the global scope object.

getGlobalVariable usage
var varVal = getGlobalVariable(varName);
  • varName (String) - the name of the global variable

Returns: varVal (??) - the value of the gobal variable

getGlobalVariable example
// retrieve the value of the 'clients' global variable
var clients = getGlobalVariable("clients");

See Also

 

include

Includes a file into the current Javascript file.

Usage:

include(path)

'path' should be the full path to the file

include example
include("/path/to/file.js");

 

 

Session

The session object provides methods that allow you to interact with the channel.

For applications written in Javascript: While the JavaScript application will continue to execute after a hangup is detected the session object will be destroyed and any attempt to access it will cause the JavaScript to terminate. Save any variables you might need for post–hangup processing and use your local variables instead.

Constructor

You can create a new session with the following:

s = new Session();

Creates an empty session object that provides methods that allow you to interact with the channel.

 

s = new Session(uuid);

Creates a session object from an existing uuid. This allows you to interact with an existing channel.

You do not need to create a default session. 'session' is created automatically for the current session and your JavaScript is running in it already. Create a new session to originate a call to a new Leg B, for example.

 

To create a new session and automatically dial out, proceeding only after the call has been answered (ignoring early media information), try this JS code:

JS outdial example
s = new Session("{ignore_early_media=true}sofia/default/foo@bar.com");
while (s.ready()) {
 // The call has been answered
}

 

 

Other options, such as those available to the originate command, may be used:

s = new Session("{ignore_early_media=true,origination_caller_id_name=Jack}sofia/default/foo@bar.com");
while (s.ready()) {
 // The call has been answered
}

Session.sayPhrase

Speaks a prompt macro using the FreeSwitch say macro API.

Usage:

session.sayPhrase(macro_name [,macro_data] [,language] [,dtmf_callback] [,dtmf_callback_args]);

Arguments:

  • macro_name - (string) The name of the say macro to speak
  • macro_data - (string) Optional. Data to pass to the say macro
  • language - (string) Optional. Language to speak macro in (ie. "en" or "fr"). Defaults to "en".
  • dtmf_callback - (function) DTMF callback function name (don't enclose it in quotes!).
  • dtmf_callback_args - (string) Optional. DTMF callback args to pass to the callback function when it is called.

Callback return values and meanings:

  • true or "true" - Causes prompts to continue speaking.
  • Any other value interrupts the prompt and returns the value from the dtmf_callback function

Macros should be placed in conf/lang_XX.xml.

sayPhrase example
  var dtmf_digits = "";
  
  function on_dtmf(session, type, obj, arg)
  {
     if (type == "dtmf") {
       console_log("on_dtmf got digit: " + obj.digit + "\n");
       dtmf_digits += obj.digit;
     }
     return(true);
  }
  
  /* Speaks a menu and waits for a single digit press. If the user does not enter a selection */
  /* then the menu is repeated up to 3 times. */
  function sayivrmenu(ivrsession, menuname, validdigits, timeout) {
      var repeat = 0;
  
      console_log("sayivrmenu: menu=[" + menuname + "] validdigits=[" + validdigits + "]\n");
  
      session.flushDigits();
      dtmf_digits = "";
  
      while (ivrsession.ready() && dtmf_digits == "" && repeat < 3) {
          /* play phrase - if digit keyed while playing callback will catch them*/
          ivrsession.sayPhrase(menuname, validdigits, "en", on_dtmf, "");
  
          /* if caller still here and has not entered any selection yet - wait for a selection*/
          if (ivrsession.ready() && dtmf_digits == "") {
              dtmf_digits = ivrsession.getDigits(1, "", timeout);
              /* if still no selection repeat menu */
              if (dtmf_digits == "") {
                  repeat++;
              }
          }
      }
      return(dtmf_digits);
  }
  
  
  var menuselection = "";
  
  /** Let's answer our call **/
  session.answer();
  
  /** Play our Main Menu prompt (options 0, 1, 2, 3 and #) **/
  menuselection = sayivrmenu(session, "mainmenu", "0123#", 6000);
  
  if (session.ready()) {
      session.execute("phrase", "saydigits," + menuselection);
  } 

Session.speak

Uses the TTS engine to say a phrase. You must have a TTS module loaded for this to work.

Usage:

speak(engine,voice,phrase,timer)

Arguments:

  • engine - the engine to use
  • voice - the name of the voice to use
  • phrase - what you want it to say
  • timer - optional timer to use (eg "soft")

In Cepstral, 'phrase' can include SSML tags as well. See http://www.cepstral.com/cgi-bin/support?page=faq&type=ssml for more info.

In Cepstral, if 'phrase' starts with / it will open the file specified and read its contents instead of a string; need windows specifics on path information

speak example
session.speak("cepstral","David","Hello from FreeSwitch");

Example with callback:

speak callback example
function my_dtmf_callback(dtmf_str, digits, args)
{
    console_log("debug", "you dialed the following " + dtmf_str + " + digits + "\n");
    return true;
}
 
//invoke thus
session.speak("cepstral", "david", '<break time="500ms"/>Hello this is a test of the break tag', my_dtmf_callback); 

Be sure not to put the name of the callback function in quotes.

 

Example of reading a file:

speak file read example
session.speak("cepstral","David","/etc/passwd"); 

 

setGlobalVariable

SPIDERMONKEY V8 UNVERIFIED

Global variables can be used to share information between all channels. You can save anything in a global variable.

This is not to be confused with a property of the global scope object.

setGlobalVariable usage
var wasSet = setGlobalVariable(varName, varValue[, valCheck]);
  • varName (String) - the name of the global variable
  • varValue (String, Object, Number) - the desired new value to be stored in the global variable
  • valCheck (String, Object, Number) - the expected old value of the global variable, used to determine if another process has since modified the value

Returns: wasSet (Boolean) - was the operation successful

Notes

The (defacto) single-process model for JavaScript engines is not honored in FreeSWITCH. This means that multiple channels can access/change the information in a variable as others are accessing. You need to take care when changing data.

For instance, this is example of a typical scenario in multi-threaded environments introduced by this deviation:

  • Global var isExtensionFree is true
  • Channel 1 reads the var and checks if it's true.
  • Channel 2 reads the var and checks if it's true.
  • Channel 1 saves value false and transfers the call to destination (since variable was true)
  • Channel 2 does the same thing since it read the var before Channel 1 managed to change it.

To avoid this problem, use valCheck. The valCheck parameter will be used to validate that no changes have been made since the getGlobalVariable call (pass the variable that you read).

  • If valCheck agrees with the current value of the global variable, the global variable will be changed to varValue and the routine will return true.
  • If valCheck does not agree with the current value of the global variable, the global variable's value will not be changed and the routine will return false.
  • If the global variable does not exist and valCheck is not a zero length string, the global variable will not be set and the function will return false.
  • If the global variable exists, varValue is a zero length string, and valCheck agrees with the current value of the global variable, the global variable will be deleted, and the function will return true.

If you do not specify valCheck, no concurrency validation will be made.

  • The global variable varName will be set to varValue
    • If varValue is a zero length string, the global variable varName will be deleted.
  • wasSet will always return true.

 

getGlobalVariable example
var gvClients = getGlobalVariable("clients");
if (gvClients === true) {
  if (!setGlobalVariable("clients", false, gvClients))
  console_log("error", "Someone changed the variable 'clients' between my get/set!");
}

See Also

system

Executes an external system command.

Usage:

var return_code = system( command );

Output of the command is not returned. If you need to send or recieve output from the command, see the File object.

system example
system("create_account");

 

TeleTone

TeleTone.addTone

Adds a tone and associates it with a 'digit' which can be alphabetic or numeric and is not limited to what is on a normal DTMF keypad.

Usage:

addTone(digit name, frequency1, frequencyN, 0.0)
  • digit name is a character that will be used to identify this tone
  • frequencies are a null terminated list of all the component frequencies that make this tone

 

AddTone example
use("TeleTone");
var tts = new TeleTone(session);
tts.addTone("q", 2600.0, 2400.0, 0.0);
dtmf = session.((FreeSwitch Javascript Session GetDigits|getDigits))(1, "", 20000, true);
if (dtmf == "q") {
  // do something fun here
}

 

TeleTone.generate

Generates a tone of a single or mixed frequencies.

Usage:

generate(TGML)

TGML is a markup language that describes the component frequencies, duration, volume, decay, and other properties. It is quite powerful and avoids the need to record an audio file to generate tone sequences.

generate example
// play the ITU E.184 'calling card bong'
use("TeleTone");
var BONG = "v=4000;>=0;+=2;#(60,0);v=2000;d(940,0)";
var newtone = new TeleTone(session);
newtone.generate(BONG); 

 

TeleTone.name

Returns the name of this Teletone object.

Usage:

name

 

name example
var tts = new TeleTone(session);
console_log(tts.name + "\n"); 

 

TeleTone.onDTMF

Causes a callback to be performed when DTMF is received.

Usage:

onDTMF(callback)

callback - The name of the function to call when DTMF is received. It will pass an argument to this callback containing the digits it received.

onDTMF example
use("TeleTone");
tts = new TeleTone(session);
function dtmf_test(digits)
{
    console_log("you pressed " + digits + "\n");
    return digits;
}

tts.onDTMF("dtmf_test");