Page tree
Skip to end of metadata
Go to start of metadata
This page describes an App that uses UnifiedAPI to place phone calls and returns the status of the call to the user.

The code is on GitHub

Download here. Do not hesitate to contribute in order to make this example better - we welcome Pull Requests!

Overview

CallMeButton is an App written in PHP that enables users to place calls. It uses the PhoneCall resource exposed by Unified API and the following requests:

  • Create PhoneCall - Creates phone calls using any given source and destination
  • List PhoneCall - Fetches the list of in progress phone calls in the system at a point of time

Installation

In order to be able to use the CallMeButton App, you need a web server with PHP 5.3 or higher installed.

STEP 1: Switch to the directory that can be accessed over web (e.g /var/www/html) and clone the Git repository:

 git clone https://github.com/4psa/app-callmebutton.git
STEP 2: Proceed to allowing permissions and ownership rights.

You also need to give proper permissions and ownership rights to the files of the App. The App needs to be owned by the web server user and group.

For example, if httpd is the name of the user and the name of the group to which the webserver belongs to:

chmod -R 755 <PATH_TO_CallMeButton>
chown -R httpd:httpd <PATH_TO_CallMeButton>
STEP 3: Configure the App.

In order to use the App, you must configure it by opening the file <PATH_TO_CallMeButton>/config/config.php and changing the following settings:

NameDescription
VN_SERVER_IPThe IP or hostname of your VoipNow server;
VN_EXTENSIONThe extended number of a phone terminal extension. This extension will be charged for the phone call.
OAUTH_APP_IDOAuth App ID or key. A 32 char-long string used by the App to identify itself with the system.
Visit this page to see how the OAuth APP ID can be obtained.
OAUTH_APP_SECRETOAuth App Secret. A 32 char-long secret used by the system to establish ownership of the App ID or key.
Based on this pair, the system will recognize the new App and will allow it to generate an access token.
Visit this page to see how the Secret can be obtained.

Please note that the newly created app will not work properly unless you check the App is trusted option in the Add App form.

Behavior

User Interface

As soon as the setup process is complete, the user may access the interface at https://<hostname>//PATH_TO_callmebutton/index.php. The following form is displayed where the user can enter his/hers phone number:

After the user enters the number and clicks the Call Me button, the App displays to the user the details of the call.

A warning about 'CURLOPT_FOLLOWLOCATION' will be generated each time the request is made. Don't worry, this is ok and it won't interfere with the request.

Internal Flow

Place a Phone Call

HTTP Request
POST /uapi/phoneCalls/@me/simple HTTP/1.1
HOST x.x.x.x
Content Type: application/json
Authorization: <OAUTH_ACCESS_TOKEN>
 
{
  "extension":"<VN_EXTENSION>",
  "phoneCallView":[
    {
       "source":["<VN_EXTENSION>"],
       "destination":["8887777"]
       "callerId":"CallMeButton <8887777>"
    }
  ]
}

The code that makes the request can be found in <Path_To_CallMeButton>/plib/lib.php and is described below:

// Fetch token
$token = getToken();
$headers = array(
   'Content-type' => 'application/json',
   'Authorization' => $token
);
 
// Initialize the cURL request
$reqUrl = 'https://'.$config['VN_SERVER_IP'].'/uapi/phoneCalls/@me/simple';
$request = new cURLRequest();
$request->setMethod(cURLRequest::METHOD_POST);
$request->setHeaders($headers); 
    
$jsonRequest = array(
	'extension' => $config['VN_EXTENSION'],				    // Number of the extension configured to run with CallMeButton
	'phoneCallView' => array(
		array('source' => array($config['VN_EXTENSION']),	// Number of the extension configured to run with CallMeButton
	          'destination' => $phoneNumber                 // The phone number entered in the form field.
     )
);
$request->setBody(json_encode($jsonRequest));

// Receive the response in JSON format
$response = $request->sendRequest($reqUrl);									     

Behavior

STEP 1: The system first calls the VN_EXTENSION

STEP 2: The system calls next the number entered by the user in the form

STEP 3: The system connects the two parties and returns the response using the JSON format. The response contains the phone call ID which is later used to fetch the call details as demonstrated below.

List the Phone Call

CallMeButton queries the server every 5 seconds to verify the status of the call and displays it to the user. This is accomplished by making the following Unified API request.

HTTP Request
GET /uapi/phoneCalls/@me/<VN_EXTENSION>/<phoneCallID>
HOST x.x.x.x
Content Type: application/json
Authorization: <OAUTH_ACCESS_TOKEN>

  • No labels

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.