User Guide

Last modified by stephane lauriere on 2015/10/20 17:11

  1. Register on your Emerginov
    1. Getting credentials
    2. Prerequisites
      1. SVN
      2. IDE
      3. VoIP clients
      4. Database
  2. Overview of Emerginov platform and components
  3. Your projects
    1. Your web Selfcare
    2. Manage your projects
      1. Join or Leave an existing project
      2. New project
      3. Manage an existing project
    3. Manage your account
  4. Upload & Commit your code
    1. Back to SVN
    2. Get sources
      1. SVN clients
      2. IDE in websvn
    3. Deploy your code
  5. Web Hosting
    1. Web Pages
    2. Database
    3. Implementing planned tasks - AKA CRON Jobs
    4. Logs
  6. API Store (AKA Nursery)
    1. Intro
    2. API subscription for your project
    3. Nursery's APIs
  7. Media Server
    1. PHP Call Management Method
    2. VXML Call Management Method
  8. How-To...
    1. VoIP client
    2. SMS Management
    3. Media and vocal services
    4. Misc
  9. SDK PHP reference guide
    1. Emerginov class
      1. Constructor
      2. Call
      3. ConfigureSMSReceiver
      4. SendSMS
      5. TextToSpeech
    2. EmerginovResult class
      1. Success
      2. Result
    3. Vocal calls SDK
      1. Answer
      2. Ask
      3. AskWithSpeechReco
      4. Call
      5. GetCallerNumber
      6. Hangup
      7. Play
      8. PlayAndAsk
      9. Record
      10. Say

Register on your Emerginov

Getting credentials

As a developer, you need credentials to log on the platform. You may ask for an account through the pre-registration file http://<your_emerginov>/pre_register.php.

You shall fill in the form, the request will be sent for validation to the administrator of the platform.

Prerequisites

SVN

You can use the on-line editor but it is highly recommended to install a SVN client to keep the code on your machine.

Info.gifAll subversion repositories can be browsed thanks to Subversion Web Pages located at https://svn.<YourEmerginov>

Thanks to this client you will be able to:

  • retrieve the code of existing projects
  • commit local code to the platform

The interaction with the SVN is mandatory to deploy the services in Emerginov.

Several clients are possible on Windows, Mac or Linux, see the comparison of SVN client.

On Ubuntu, you can install SVN using the command line
sudo apt-get install subversion

Please note that if you are working behind a proxy you may have some issues and you must configure your client to manage the proxy.

IDE

Eclipse, Geany, Bluefish, Emacs, VIM....

VoIP clients

Twinkle, Linphone, x-lite, Ekiga,...

see FAQ VoIP

A WebRTC client is available on the last version of Emerginov. A link is provided in the self-care page.

Database

MySQL and MySQL workbench to create your tables.

Overview of Emerginov platform and components

The Emerginov Platform may be described as follow:

Archidevsimple.png

All interesting components for developers are are the followings:

  • The Media Server: this can be used to build Voice application in VoiceXML or PHP. Files are located in Project Web Pages
  • The Web Server: this can be used to host web pages. Files are also located in Project Web Pages
  • The MySQL database: this can be used to store data. The MySQL database can be requested from PHP pages under Project Web Pages (so from Media Server and Web Server)
  • The Source Code Manager Subversion: this can be used to manage your service source code.

To retain

Vil-idee.gifThe web pages of your project are hosted in a common location for both your Web Server and your Media Server.

The database is available at db.emerginov.locanetl for your project

Your projects

Your web Selfcare

You can connect to your self-care if you got credentials. Log into your self-care page http://<YourEmerginov>/main_authen/selfcare.php.

if you forgot the link, do not panic! Just go on the main page http://<YourEmerginov>

One of the menu will lead you to the self-care page

portal-user-main-2.png

A new web page shall be displayed. This page can be divided into 2 parts:

  • manage your projects
  • manage your account

portal-user2-selfcare.png

You must authenticate to access to this page. The credentials are provided by mail sent after registration.

Manage your projects

You will get a view of the projects you are involved in.

The other functions are:

  • join or leave an existing project
  • create a new project
  • access your existing project

To get details on a specific project you must click on it

Join or Leave an existing project

You must click on the menu.

A new page is displayed.

portal-user-joinleave.png

When you want to join an existing project, you must select the project in the list of projects then click on Join. Once clicked the demand is transmitted to the administrator who must validate it.

There is no validation required for leaving a project.

New project

This part will allow you to ask new resources for a new project.

You may have a look at the video tutorial on project creation.

portal-user-create.png

You shall

  • describe the project
  • add tags
  • select the licence (by default Apache 2.0 or GNU GPL v2)
  • ask for a MySQL database
  • ask for a PSTN routable number so your application could be reached from any mobile devices.

The creation will be effective only after a validation by the platform administration.

Manage an existing project

Each project page has several tabs

  • General information: modify the description, add tags
  • Members: see the other participants
  • Subversion Sources: access to the source code
  • Configuration: deployment configuration, vocal configuration
  • Cron job: management of planed tasks
  • Logs

portal-user-selfcare2-info.png

The deployment mechanism is described ### as well as the way to use cron jobs and the logs, see ###.

Manage your account

You can change the passwords (for SVN only)

In this section, you can also edit your Emerginov Mailing Lists subscription.

To retain

Vil-idee.gifThe registration is done automatically through the USB key.

Once registered you have access to your personal self-care page The self-care page can be used to

  • ask for the creation of new projects
  • monitor the projects you are involved in
  • change your SVN password

Upload & Commit your code

Back to SVN

A question that occurs frequently when using Emerginov is why using a subversion repository? Why can't we use FTP to publish new files on web server? I'll try to explain this technical choices.

First of all, the Subversion repository is designed to be used by many people together (community approach of micro services development). With subversion, many developers can develop in the same time on the same project. Moreover, with Subversion, it is easy to see the evolution of the project sources (and even visualize it). It is also possible to revert sources to old ones if necessary. No mistake is possible with Subversion.

With a FTP server, it is not possible to revert to old files if a mistake occurs, so developers must use it carefully in order to prevent code override. Co-development is very difficult to manage with FTP access.

That is why we decided to use Subversion and a deployment mechanism in Emerginov.

Each project has a subversion repository.

In this repository, you can find the '''source code''' of the project.

The initial repository is created with a standard folder tree as follow:

|--branches
|--tags
|--trunk
     |--web
        |--media
        |--passwords.php

As you can see in the standard tree created with your project, a file and a folder are already populated in the repository:

  • media folder
  • passwords.php file

The media folder is used to store audio files. This folder is automatically readable by the Media Server so files can be played easily.

The passwords.php file is used to store passwords (for example MySQL and Nursery passwords).
For security reasons, this file is the only file that cannot be read by everybody. Only developers of the project will be able to read the file.

Remember that all the sources of all the projects are readable by everybody (except the ''passwords.php'') as your project is under Libre or Open Source license.

To retain

Vil-idee.gifRemember that all the sources of all the projects are readable by everybody (except the passwords.php) as your project is under Libre or Open Source license.

Get sources

SVN clients

You can get sources of your project by using a Subversion tool.

On Ubuntu:

  • CLI (Command Line Interface) client is svn (in subversion package)
  • GUI (Graphic User Interface) client is rapidsvn

On Windows:

  • CLI client is ...
  • GUI client is either rapidsvn or tortoisesvn

When your client is setup, you can use it to checkout the source code:

  • CLI (replace projectname with your project name):
svn checkout  projectname
  • Using RapidSVN is very easy, you'll find it!

As soon as you want to add a file or a folder in your source code repository, you can use:

svn add foldername

When every modification is done locally, you can use the commit command to push changes to Emerginov repository server:

svn commit

Typically when creating a new project, you are notified by mail that the project has been created then the first svn checkout will retrieve the basic tree structure detailed above.

To retain

Vil-idee.gifSubversion is used to manipule the sources of your project. Here are the main svn commands you should use on your computer:
  • checkout: svn checkout https://<YourEmerginov>/projects/projectname projectname
  • add: svn add foldername
  • commit : svn commit
  • more details on svn official web site

IDE in websvn

You may also use the web IDE integrated in websvn on https://svn.<your_emerginov>

If you log on websvn you may see all the files and folders of your project as follow:

EmerginovIDE.png

You can use the "Emerginov Editor"  to edit, add, modify or delete files or folders in the SVN.

For example, if you click on filenew.png you can create a new file in the current directory . It will open another tab in your browser. You can edit code into the page and save the code using CTRL+S.

To modify an existing file click on fileedit.png

To create a new folder click on foldernew.png.

You can also delete a file or a folder.

The Emerginov editor is quick and nice for demo but it is recommended to get the code on your machine through a SVN client.

Please also note that by construction Emerginov platforms host micro service under free license, it means that before starting developing your code, you may take some minutes to see if it does not already exist emoticon_smile If so, the free license software license allows you to access, edit, modify and distribute an evolution of the existing project. re-use as much as possible...

Deploy your code

We assume that your code is available on the SVN. It can be deployed.

Understand the deployment mechanism

The deployment mechanism is a mechanism that will copy all your source files to the correct destination folders in order to be visible from the web. This will also configure your Media Server project vocal kiosk.

The first thing done is the web deployment: All the trunk/web/ folder is copied into your Project Web pages space. As soon as this part is done, your project can be browsed with an URL like: http://project.<YourEmerginov>/projectname/  (please note that you must have chosen a free license prior to any deployment, a code without license cannot be deployed)

In a second step, the media server is configured depending on your project properties.

How to deploy

To deploy your project, please go to the http://<YourEmerginov>/main_authen/selfcare.php page:

On this page, you shall find all your projects click on the project you want to deploy.

A new page dedicated to this specific project shall be displayed:

Select Configuration tab:

portal-user2-selfcare-config.png

If the project is not yet deployed, click on Deploy it.

If the project is already deploy you can Undeploy it or force the redployment using Redeploy it.

The status of the project (Deployed or Undeployed) is indicated at the beginning of the section.

You can also activate the automatic deployment if not already done. With this function, as soon as your projet sources are commited, the deployment will be automatically done. This is very usefull. Please note that  you must deploy your project at least once before using automatic deployment.

To retain

Vil-idee.gifRemember that when you first commit sources of your project in the subversion repository, the sources are not yet deployed. You must use the deploy it button in the http://<YourEmerginov>/main_authen/selfcare.php selfcare to do it.

Web Hosting

Web Pages

Your project can use web pages. The web pages can use the PHP script language on server side.

Info.gifFor more information about PHP, see http://en.wikipedia.org/wiki/PHP

In an initial Subversion tree, the web pages are located under the ''trunk/web/'' folder:

If you need specific php libraries, you must contact your administrator.

To retain

Vil-idee.gifYour project web pages sources are under trunk/web/ folder in the Subversion repository

From this folder, the web pages can be deployed to an Apache-MySQL-PHP (AMP) server when you click on the deploy it button. If automatic deploy is activated, you won't need to click on this button. The deployment is automatically done.

Misc:

  • The passwords.php file is the only file that is not readable by everybody, use it to store passwords!
  • Remember that your project-ROOT folder is accessible thanks to the $_SERVER['DOCUMENT_ROOT'] variable

Links:

  • Sources browsing: https://svn.<YourEmerginov>/
  • Selfcare (deploy button) http://<YourEmerginov>/main_authen/selfcare.php
  • Your project link when deployed: http://projects.<YourEmerginov>/projectname/
  • List of projects in platform: http://<YourEmerginov>/projects-list.php

Database

Most projects use databases to store data or information like users, accounts, etc.. Your project can also use a database if you ask for it during the creation procedure (see ##).

Your database can be used from web space thanks to PHP standard MySQL functions

If you want to manage your database with a graphical environment, we provide a PHPMyAdmin interface: https://phpmyadmin.<yourEmerginov>/

Try browsing this page, '''you should be asked for a login/password twice, this is the normal behavior!'''. See ## for more information about security and passwords in Emerginov.


Your project can use a MySQL database. The main parameters are:

  • server: db.emerginov.local
  • database: proj_projectname_XXXXXXX
  • login: projectname
  • password: received by mail

To retain

Vil-idee.gifYour project can use a MySQL database. The main parameters are:
  • server: db.emerginov.local
  • database: proj_projectname_XXXXXXX
  • login: projectname
  • password: received by mail

Links:

  • PHPMyAdmin: https://phpmyadmin.<YourEmerginov>

Implementing planned tasks - AKA CRON Jobs

As your project might need some task to be executed at scheduled time. This is what we call cronjobs.

To add a cronjob to your project, follow these steps:

  • Connect on Emerginov selfcare: www.<YourEmerginov>/main_authen/selfcare.php
  • Select your project
  • Select the '''Cron job''' tab
  • You can manage your cronjob thanks to the specific Scheduled Task tab

portal-user2-selfcare-cron.png

The cronjobs can be used as UNIX cronjobs.

Logs

When someone access your pages or if an error occurred, you can see logs with the specific tabs available in your self-care.

The logs available under this section are:

  • Cron logs
  • Apache Error and Access logs
  • Automatic deploy logs
  • Calls logs corresponding to any print_r or echo in your media files

portal-user2-selfcare-logs.png

API Store (AKA Nursery)

Intro

Nursery is the API shop element. It will provide you some Telecom-related Application Programmable Interfaces (API).

Basically the admin of your platform will expose some APIs through the nursery with access and quota management. As an example, one cool thing is that you will be able to send and receive SMS from your application.

API subscription for your project

You can subscribe to the API for your own projects. A nursery account is automatically created during the creation of your account.

Once the project has been validated, you can, from your self-care page go to the nursery.

selfcare-api.png

You will access to a new page

nursery1.png

On this page you will see the list of the projects you are in charge of, one line per project.

You can click on the project name to get details and/or click on API's store to go API shopping.

nursery3.png

On the left column, you can see the API you already subscribed to, on the right column you can see the API you can subscribe to.

For exemple , if you wish to send or receive SMS, your project should subscribe to the API and provide some information related to the API (e.g. for SMS sending, estimation of the traffic per second, day and month).

Do not forget to save your changes!

The API subscription must be validated by the administrator before becoming effective.

Please note that the Nursery credentials are automatically put in the passwords.php file with all the other creds.

Nursery's APIs

The Nursery can be used for many API. For now, those are available:

  • Sending SMS
  • Receiving SMS
  • Making outgoing calls
  • TestToSpeech

Nursery is used as an API provider and a security proxy.
Misc:

Links

See the How-To to have code illustration of API.

Media Server

The Media Server will use your callback file (configured under Personal Account) in order to control your vocal kiosk.

You can choose between two call management methods: 

  • PHP call management
  • VoiceXML

PHP Call Management Method

Managing your vocal kiosk with PHP is very easy thanks to many Emerginov built-in methods such as:

  • Answer()
  • Ask()
  • Call()
  • Hangup()
  • Play()
  • PlayAndAsk()
  • Record()
  • Say()
  • more to be coming soon...

Each method is described in SDK PHP Reference guide

VXML Call Management Method

If your a king developer in VXML language, you can of course use it to build your vocal kiosk. Emerginov is based on VoiceGlue. You will find information about it on their website.

The VXML engine is not yet automatically installed on an Emerginov platform. This is something that must be done manually...

How-To...

VoIP client

How to configure a VoIP client

SMS Management

How to send an SMS from a project

How to receive and manage SMS in a project

Media and vocal services

How to create a media file with TTS API

How to create my first vocal service in PHP

How to create my first vocal service in VXML

How do I make an outgoing call

How to record a call

How do I get the incoming party number in vocal services?

Misc

How to access the database

How to send mail from php

How to create 2 tasks in 1 cronjob?

How do I fork an existing project

SDK PHP reference guide

Emerginov class

This class can be used by including ''Emerginov.php'' file in your project:

<?php
require_once("Emerginov.php");
?>

Constructor

Description
 Build a new Emerginov object

Parameters
 $api_login: this is your project Nursery login (you usually found it in passwords.php file)
 $api_password: this is your project Nursery password (you usually found it in passwords.php file)

Return
 A new Emerginov Object

Example usage

<?php
$e = new Emerginov($api_login, $api_password);
?>

Call

Description
 Make a call between your project and a number. Before using this method, you must subscribe the Outgoing Call API on API Shop tab of your project.

Parameters (''italics'' are optionals)
 $number: the number to call. This can also be an user login that is registered with a VoIP client. See How to configure a VoIP client
 $callback: the callback file that must be used by the media server. This parameter is optional. Default value is incoming.php and can be change on your project configuration tab.
 $timeout: the number of millisecond to wait for answering. Default is 70000 (70 seconds).

Return
 A new EmerginovResult (see EmerginovResult class for details)

Example usage

<?php
$r = $e->Call("+33123456789");
echo ($r->Success) ? "Ok!" : $r->Result;
?>

ConfigureSMSReceiver

Description
 Configure the XMSMO API for this project. Before using this method, you must subscribe the XMS-MO API on API Shop tab of your project.

Parameters (''italics'' are optionals)
 $callback: the php callback file that must be called when a SMS is incoming to your application.
 $keywords: this is an array containing all keywords your application must listen on. Every SMS the Emerginov platform receives starting with one of these keywords will be routed to your application.
 $msisdns: this is an array containing all MSISDN (phone numbers) your application must listen on.
   All SMS coming from those MSISDN will directly be routed to your application.

 If no parameters are defined, the configuration will be deleted 

Return
 If no parameters are defined, then the method return an new EmerginovResult class (see EmerginovResult class for details)
 If the $callback parameter is ''not null'', then the method return an new XmsmoService. (see below)
 On Error, it will return an new EmerginovResult class

XmsmoService

Description
 This class is used to manipulate your project XMS-MO API settings. It has many methods:

addKeyword

Description
 This method is used to add a keyword your application must listen on. Every SMS the Emerginov platform receives starting with this keyword will be routed to your application.

Parameter
 $keyword: The keyword to add.

Return
 A new EmerginovResult to tell you if everything went fine (an error might occur if this keyword is already used).

addMsisdn

Description
 This method is used to add a MSISDN your application must listen on. Every SMS the Emerginov platform receives from this phone number will be routed to your application.

Parameter
 $msisdn: The MSISDN (phone number) to add.

Return
 A new EmerginovResult to tell you if everything went fine (an error might occur if this MSISDN is already used).

getService

Description
 This method is used to get your project current configuration.

Parameter
 none

Return
 A new Service object representing your configuration (informative).

removeKeyword

Description
 This method is used to remove a keyword your application must listen on.

Parameter
 $keyword: The keyword to remove.

Return
 A new EmerginovResult to tell you if everything went fine. See EmerginovResult class for more details.

removeMsisdn

Description
 This method is used to remove a MSISDN your application must listen on.

Parameter
 $msisdn: The MSISDN (phone number) to remove.

Return
 A new EmerginovResult to tell you if everything went fine. See EmerginovResult class for more details.

Example usage

<?php
require_once("passwords.php");
require_once("Emerginov.php");

$Emerginov = new Emerginov($api_login, $api_password);

echo "Create a new blank SMSReceiver\n";
$SMSReceiver = $Emerginov->ConfigureSMSReceiver("SMSReceiver.php");

echo "Add a keyword... ";
$res = $SMSReceiver->addKeyword("arnaud");
echo ($res->Success) ? "Ok!\n" : $res->Result . "\n";

echo "Add a keyword... ";
$res = $SMSReceiver->addKeyword("canards");
echo ($res->Success) ? "Ok!\n" : $res->Result . "\n";

echo "Remove an other keyword... ";
$res = $SMSReceiver->removeKeyword("arnaud");
echo ($res->Success) ? "Ok!\n" : $res->Result . "\n";

echo "Add a Msisdn... ";
$res = $SMSReceiver->addMsisdn("+33786023023");
echo ($res->Success) ? "Ok!\n" : $res->Result . "\n";

echo "Remove this Msisdn... ";
$res = $SMSReceiver->removeMsisdn("+33786023023");
echo ($res->Success) ? "Ok!\n" : $res->Result . "\n";

echo "Reset the SMSReceiver... ";
$res = $Emerginov->ConfigureSMSReceiver();
echo ($res->Success) ? "Ok!\n" : $res->Result . "\n";

print_r($SMSReceiver->getService());
?>

SendSMS

Description
 This method let you send SMS. Before using this method, you must subscribe the SMSSender-REST API on API Shop tab of your project.

Parameters
 $number: the number to send to.
 $content: the SMS content. If content is over 160 characters, more than one SMS may be sent, please take care of this when you provide SMS quotas on API subscription mechanism.

Return
 A new EmerginovResult (see EmerginovResult class for details)

Example usage

<?php
$r = $e->SendSMS("+33123456789","hello");
echo ($r->Success) ? "Ok!" : $r->Result;
?>

TextToSpeech

Description
 This method let you convert text to a media file (wav format).

Parameters (''italics'' are optionals)
 $text: the text to convert.
 $filename: the file to save the resulting wav.
 $lang: the lang to be used to read the text. Default is "fr", can also be "en", or any other language that google support.

Return
 A new EmerginovResult (see EmerginovResult class for details)

Example usage

<?php
$r = $e->TextToSpeech("Bonjour le monde", "media/bonjour.gsm", "fr");
echo ($r->Success) ? "Ok!" : $r->Result;
?>

EmerginovResult class

This class is automatically included by ''Emerginov.php'' file. It is used to structure the return from Emerginov methods

Class constructor:

  • None available for developers as only used by Emerginov class

Methods available:

  • None

Public variables:

  • EmerginovResult->Success
  • EmerginovResult->Result

Success

The Success variable is boolean (True, False). It contains the result of an Emerginov method call. If the call has been done successfully, then Success is True, else, Success if False.

Result

The Result variable can contain any value return by Nursery mechanism. This is often an array containing information or result from the requested method. Il can also contain an error array if Success if false.

Vocal calls SDK

Your callback file is the file that will control the media server to build vocal kiosk. Every project has a default callback file: *incoming.php*.

Answer

Description
 Just answer the line!

Parameters
 None

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data). Result=0 on success, -1 on failure

Example usage

<?php
$call->Answer();
?>

Ask

Description
 The user has the opportunity to press a key at any time during the message or the 6 seconds post-message silence.
 If the user presses a key while the message is playing, the message stops playing.
 If no digits are pressed then 6 seconds of silence follow the message.
 Pressing the # key ends the command. When ended this way, the command ends successfully with any previously
 keyed digits in the result. A side effect of this is that there is no easy way to read a # key using this command.
 However, it is possible to read a single # key, as the result will be empty, but the timeout attribute will not be present.

Parameters (''italics'' are optionals)
 $text: this is the text to say while user can press a button
 $api_login: this is your API project login.
 $api_password: this is the API project password.
 $voice: the voice to use. Default is "fr", can also be "en", or any other language that google support.
 $timeout: When the first key is pressed a timer starts counting for $timeout milliseconds.
   Every time the user presses another key the timer is restarted.
   The command ends when the counter goes to zero or $max_digits are entered, whichever happens first.
   If no $timeout is specified, default is 2000 milliseconds.
 $max_digits: If you don't specify $max_digits, then the user can enter as many digits as he wants.

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data).
 result holds DTMF entered by user
 data holds the timeout if present

Example usage

<?php
$r = $call->Ask("Bonjour le monde", $api_login, $api_password, "fr");
print_r($r);

/*
This will output (I pressed 42):

Array
(
    [code] => 200
    [result] => 42
    [data] => timeout
)
*/

?>

AskWithSpeechReco

Description
 The user will hear a message (and eventually a BEEP sound) asking him to say something. The speech will then be translated to text thanks to a Google Speech Recognition API.
 The speech detection ends after 2 seconds silence. Also, pressing the # key ends the command.

Parameters (''italics'' are optionals)
 $text: this is the text to say for asking the user to speak.
 $api_login: this is your API project login.
 $api_password: this is the API password.
 $voice: the voice to use. Default is "fr", can also be "en", or any other language that google support.
 $lang: the lang to use to try translating speech to text. Default is "fr", can also be "en", or any other language that google support.
 $google_api_key: the google API key to be used. Please read this to learn how to get a key: http://www.chromium.org/developers/how-tos/api-keys
 $escape_digits: default is "#"
 $timeout: the maximum record time in milliseconds, or -1 for no timeout. Default is "30000" (30 seconds).
 $beep: boolean (true, false) that determine if BEEP must be played before recording begins. Default is true
 $silence: the number of seconds of silence allowed before the function returns despite the lack of dtmf digits or reaching timeout. Default is "2" seconds.

Result
 Return an Array ('detected_speech'=>"the text said bu user", 'confidence'=>float_number).
 The confidence float number may vary between 0 and 1. A value close to 1 means a better confidence of the detected_speech.

Example usage

<?php
// Please use passwords.php to store your $google_api_key
require_once ("passwords.php");

$r = $call->AskWithSpeechReco("Bonjour le monde", $api_login, $api_password, "fr", "fr", $google_api_key);
print_r($r);

/*
This will output (I said "Bonjour"):

Array
(
    [detected_speech] => Bonjour
    [confidence] => 0.81851262
)
*/

?>

Call

Description
 This method can be used to make a call between a phone number and your vocal kiosk (your callback file).
 Before using this method, you must subscribe the Outgoing-Call API on API Shop tab of your project.

Parameters (''italics'' are optionals)
 $number: this is the number to connect with your vocal kiosk. This can also be an user login that is registered with a VoIP client. See How to configure a VoIP client.
 $timeout: The timeout parameter is optional. If not specifed, the Dial command will wait indefinitely, exiting only
   when the originating channel hangs up, or all the dialed channel return a busy or error condition. Otherwise it specifies a maximum time, in seconds, that the Dial command is to wait for a channel to answer.
 $options: See http://www.voip-info.org/wiki/view/Asterisk+cmd+Dial#Options

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data). For now, the result will let you know if the command had been
 queued successfully but you can't know if the called party has answered (this is like an asynchronous mechanism).
 This behavior will be improved in a near future.

Example usage

<?php
$r = $call->Call("arnaud.morin");
print_r($r);

/*
This will output:

Array
(
    [code] => 200
    [result] => -1
    [data] =>
)
*/

?>

GetCallerNumber

Description
 Try to get the Caller Number. It could be a phone number (like +33123456789) or a SIP address (like arnaud.morin).

Parameters
 None

Result
 Return a string containing te caller number

Example usage

<?php
$whoIsCalling = $call->GetCallerNumber();
?>

Hangup

Description
 This will hangup the line. If you forgot to do it at the end of your PHP file, we will do it for you.

Parameters
 None

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data).
 Result=1 on success, -1 on failure

Example usage

<?php
$call->Hangup();
?>

Play

Description
 This method is used to play an audio file

Parameters (''italics'' are optionals)
 $filename: The file that will be played. The file must be located under your project ''media'' folder!
   Also, you must not provide the file extension. E.g.: let's say that you want to play the following
   file: ''media/audiofile.wav'', then, you should use play as follow: $call->Play("audiofile");
 $escape_digits: If provided, allowing playback to be interrupted by the given digits. Default is "#".
 $offset: If provided then the audio will seek to sample offset before play starts. Default is 0.

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data).
 result is -1 on hangup or error, 0 if playback completes with no digit received,
 otherwise a decimal value of the DTMF tone.

Example usage

<?php
$r = $call->Play("echo_test");
print_r($r);

/*
This will output (I pressed # before the end of the speech):

Array
(
    [code] => 200
    [result] => 35
    [data] =>
    [endpos] => 16480
)

Sample output without pressing #

Array
(
    [code] => 200
    [result] => 0
    [data] =>
    [endpos] => 0
)
*/

?>

PlayAndAsk

Description
 This method is used to play an audio file and ask the user to press a digit on his phone afterward.

Parameters (''italics'' are optionals)
 $filename: The file that will be played. The file must be located under your project ''media'' folder!
   Also, you must not provide the file extension. E.g.: let's say that you want to play the following
   file: ''media/audiofile.wav'', then, you should use play as follow: $call->Play("audiofile");
 $timeout: When the first key is pressed a timer starts counting for $timeout milliseconds.
   Every time the user presses another key the timer is restarted.
   The command ends when the counter goes to zero or $max_digits are entered, whichever happens first.
   If no $timeout is specified, default is 2000 milliseconds.
 $max_digits: If you don't specify $max_digits, then the user can enter as many digits as he wants.

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data).
 result holds DTMF entered by user
 data holds the timeout if present

Example usage

<?php
$r = $call->PlayAndAsk("echo_test");
print_r($r);

/*
This will output (I pressed 42):

Array
(
    [code] => 200
    [result] => 42
    [data] => timeout
)
*/

?>

Record

Description
 Record sound to a file until an acceptable DTMF digit is received or a specified amount of
 time has passed. Optionally a BEEP is played before recording begins.

Parameters (''italics'' are optionals)
 $file: The file to record, without extension. The file will be created in project ''media'' folder
 $format: format of the file. ''gsm'' and ''wav'' are commonly used formats. ''mp3'' is read-only and thus cannot be used.
 $escape_digits: Default is '#'.
 $timeout:  is the maximum record time in milliseconds, or -1 for no timeout. Default is "-1".
 $offset: offset to seek to without exceeding the end of the file. Default is null.
 $beep: boolean (true, false) that determine if BEEP must be played before recording begins. Default is true.
 $silence: the number of seconds of silence allowed before the function returns despite the lack of dtmf digits or reaching timeout. Default is "2" seconds.

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data).
 result is -1 on error, 0 on hangup, otherwise a decimal value of the DTMF tone.

Example usage

<?php
$r = $call->Record("record","wav");
print_r($r);

$call->Play("record");

/*
This will output:

Array
(
    [code] => 200
    [result] => 99999
    [data] => timeout
    [endpos] => 23040
)
*/

?>

Say

Description
 This method is used to say a text with TextToSpeech.

Parameters (''italics'' are optionals)
 $text: The text that must be said
 $api_login: this is your API project login.
 $api_password: this is the API project password.
 $voice: the voice to use. Default is "fr", can also be "en", or any other language that google support.
 $escape_digits: default is "#"
 $delete: the Say method will create a wav file under your project ''media'' folder before playing it. After the play, the file will be deleted by default.
   Turning $delete to *false* will keep this file in your ''media'' folder.

Result
 Return an Array ('code'=>$code, 'result'=>$result, 'data'=>$data).
 result is -1 on hangup or error, 0 if playback completes,
 data is a small text describing result

Example usage

<?php
$r = $call->Say("Bonjour tout le monde", $api_login, $api_password, "fr");
print_r($r);

/*
This will output:

Array
(
    [code] => 200
    [result] => 0
    [data] => Success playing Bonjour tout le monde
)
*/

?>
Tags:
Created by stephane lauriere on 2012/09/13 11:38

Partners

Orange

VOICES

EU - FP7

OW2

© Emerginov
Site maintained by OW2