NAV

Introduction

API Endpoint

https://api.fonoster.com/v1

Fonoster makes voice application easy by combining powerful call control, and RESTful APIs. In just minutes you can build, test and deploy solutions that scale at the speed of your business.

You use Javascript to control the flow of the phone call, and the REST API to originate the call, obtain analytics, manage accounts, create apps, configure numbers, retrieve recordings or transcriptions, and more.

Call Control

App Example

loadJS("fn:http.js");

// Get fruits from json resource
$http.get('https://someurl.com/fruits.json').then(function(result) {
    var fruits = JSON.parse(result.body);
});

fruits.forEach(function(fruit) {
    say(fruit.name);
});

Use any combination of the Voice Verbs to obtain call control. This “Verbs” were created with a principle in mind, that a simple problem should have an easy solution.

The following six verbs are provided for easy use:

Fonoster also provides an Http Object, inspired in Unirest, to enable I/O via HTTP/S. A description of the verbs and the Http Object follows.

Answer

Example

wait(5); answer(); say('You waited for 5 seconds');

Use Answer to answer to a call. This verb is optional and must be use in conjunction with autoanwser to work properly.

This is useful in situations when you want to execute and action prior to beginning the call, for instance pre-load data using the Http Object.

Hangup

Example

say('Hello world');
var cnt = 3;

while(true) {
    say('The counter is equal to: ' + cnt);
    if (cnt == 0) hangup();
    cnt--;
}

Calls will be terminated when all instructions are completed. With the Hangup verb you can terminate the call anytime you need.

Attribute Description Optional
timeout Time in seconds to auto-hangup Yes

Play

The Play verb is used to stream a pre-recorded audio.

Example

// The file must be previously uploaded using the REST API.
play('tt-monkeys');
Attribute Description Optional
file The file must be uploaded prior to use this verb. No
timeout Time in seconds to wait for the user to press the keypad. If no key is pressed an empty character will be returned. Yes

Say

Example

// Setup the call's voice
voice('sofia');
say('Hello, I am Sofia!');

// Or pass the desired voice as parameter
say('Hola, enhorabuena!', {voice:'enrique'}); // Spanish male voice

The verb Say uses a powerful text2speech engine, that transform your text into beautiful voices. There are many voices and languages that you can choose.

The maximum text size is 4kb. Commas and periods will cause pauses, and may speak things such as abbreviations or times differently than you expect so be sure to double check for correct pronunciation.

Available Voices:

Gather

Example

var config = {timeout: 10, numDigits: 1};
var key = gather(say('Choose a number from your keypad'), config);
say('The key pressed was, ' + key);

Gather collects data from the user’s keypad. This verb must be used in combination with Wait, Say or Play. The possible parameters are:

Attribute Description Optional
function The function Wait, Say or Play or a character (0-9, *, #) No
config Modifiers to change the verbs behavior. Default is {timeout: 4, finishOnKey: ’#’, numDigits: 0}. The parameter numDigits indicate the maximum number of digits allow for the entry. Yes

Record

Example

var config = {
    beep: false,
    maxDuration: 3600, 
    timeout: 5,
    finishOnKey: '#'
};
var result = record(config);
stash('recordingUri', result.recordingUri);

The Record verb records the caller’s voice. Like the other verbs, it has a default behavior that can changed using the modifiers.

Attribute Description Optional
config Modifiers to change the verbs behavior. Default is {beep: true; timeout: 5, finishOnKey: ‘1234567890*#’, maxDuration: 3600}. The parameter maxDuration indicate the maximum time for the record. No

Stash

Example

var t = new Date();
stash('time', t);
say('Adios!', {voice: 'enrique'});

Use stash to store variables as metadata with the call-record. Stashed data can later be retrieved as part of the CDR. This feature is particularly interesting for analytics.

Attribute Description Optional
name Name of the variable No
value Value to store No

Wait

Example

say('Please wait')
wait(10)
say('Thanks for waiting');

Plays silence for the given time.

Attribute Description Optional
duration Time in second for the duration of the silence No

Http

Basic Example

loadJS("fn:http.js");

$http.get('https://someurl.com/some.json')
then(function(result) {
    var list = result.body
})

Change the content type to text. (default is JSON)

loadJS("fn:http.js");

$http.get('https://someurl.com/some.txt')
.header('content', 'text') 
.then(function(result) {
    var txt = result.body
})

Example using POST

loadJS("fn:http.js");

$http.post('https://someurl.com/users')
.field('id', '1234') 
.field('name', 'Enrique Ricardo') 
.then(function(result) {
    stash('code', result.code);
})

BasicAuthentication Example

loadJS("fn:http.js");

$http.post('https://someurl.com/users')
.basicAuth('username', 'pass')
.queryString('gender', 'MALE')
.then(function(result) {
    var users = result.body;
    users.forEach(function(user) {
        say(user.firstName);
    });
})

The Http Object is inspired in Unirest and is available for you to send and retrieve data via HTTP/S.

Initiate the call by invoking the appropriate method(get, put, post, delete, head), use a modifier if need, then call .then() to send the request. Results will be provided via a Callback.

The available HTTP methods are:

You may stack as many modifiers as needed just keep in mind that a method, whichever you choose, must be call before any modifier. Also, every call will produce a result in the form of {code:'Some HTTP Code’, body: 'Some content’}.

RESTful API

Authentication

Getting The Credentials

curl -u "john@doe.com:osamayor" https://api.fonoster.com/v1/users/credentials

GET https://api.fonoster.com/v1/users/credentials

Obtain your Account Id and Token by making a call to the credentials resource. You will use this later to perform BasicAuthentication. Your credentials are also available in Fonoster’s console.

Make a call

Call Example

curl -vkH "Content-Type: application/json" \
-u "5678c1a440307c529ceb66c5:61b17c2f33834c429ac53a2f8a1ff333" \
-XPOST --data '{"appId":"5678f0ee40307c6728f60c4b", \
                "from":"+17066041487", \
                "to":"+17065935971"}' \
https://api.fonoster.com/v1/accounts/5678c1a440307c529ceb66c5/calls

POST https://api.fonoster.com/v1/accounts/{Account Id}/calls

Making a call with Fonoster is easy with curl. You must send the following parameters.

Attribute Description Optional
appId Find this in the dashboard No
from Origin in E.164 format No
to Destination in E.164 format No
sendDigits Play DTMF before call Yes
timeout Hangup after timeout elapsed(default is 60 seconds) Yes
record Whether should record the call Yes
autoanwser Tells the engine whether or it should answer this call (use in combination with the Answer verb) Yes

Tutorials

Survey Tutorial

Full Code

var candidates = {
  "1": "{name:'Donald Trump'}",
  "2": "{name:'Hillary Clinton'}",
  "3": "{name:'Benny Sanders'}"
};

// Force hangup after two minutes
hangup(120);
voice('lisa');

say('Hello, this is a presidential poll from the Georgia Statistics Center.');

var keyPressed = gather(say('If you would like to be remove from our list, press 7'), {timeout: 10, numDigits: 1});

if (keyPressed == 7) {
    http.post('https://georgia.gov/removeFromList')
    .timeout(5000)
    .basicAuth("username", "password")
    .then(function(result) {
        if (result.body == 'OK') {
            say('You have been remove from our list');
        } else {
          // Do nothing
        }
     });
}

// Configure the behavior of _gather_
var config = {
    finishOnKey: '*',
    timeout: 1,
    numDigits: 1
};

while(true) {
    var keyPressed = gather(say('For Trump Press one. For Hillary, press two and for Sanders 3'), config);

    if (keyPressed != '1' && keyPressed != 2 && keyPressed != 3) {
    say('I could not register your selection. Lets try again.');
        continue;
    }

    // Store with call record
    stash('candidate', keyPressed);
    say('You selected option ' + keyPressed + ', ' + candidates[keyPressed].name);
    break;
}

say('Thanks for participating in this poll. To review the results, go to www.georgia.gov. Goodbye!');

This tutorial shows how to write a survey with Javascript and the RESTful API. The requirements are as follows:

Let’s start by creating the list of candidates

Next, let’s tell our app that it must hang up once two minutes have elapsed. We will also use voice(‘lisa’) to set Lisa (a female English voice) as the default voice (For more voices, check out the Say verb documentation).

Let’s now use the verb Gather to ask the customer if it wants to get off the call-list. Remember, that the Gather verb must be used in combination with Wait, Say or Play.

The final step is to ask the customer for the candidate of choice and Stash the result with the call-record.