Excerpt |
---|
This page describes an App that uses UnifiedAPI to place phone calls and returns the status of the call to the user. Download. |
Table of Contents | ||
---|---|---|
|
Note |
---|
This demonstrative code SHOULD NOT be used in production. It is designed to simply show how an App interacts with UnifiedAPI. From this perspective, validations and error-checks aiming to demonstrate the most common mistakes are minimal and can be done easily. |
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
It is an excellent starting point for any PHP developer.
Installation
In order to be able to use the CallMeButton App, you need a webserver with PHP 5.3 or higher installed.
STEP 1: Download the files.
Download the archive, extract the files, and copy them to a directory that can be accessed over the Web.
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:
Code Block |
---|
chmod -R 755 <PATH_TO_CallMeButton> chwon -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>/interface/config/config.php
and changing the following settings:
Name | Description |
---|---|
VN_SERVER_IP | The IP or hostname of your VoipNow server; |
VN_EXTENSION | The extended number of a phone terminal extension. This extension will be charged for the phone call. |
OAUTH_APP_ID | OAuth 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_SECRET | OAuth 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. |
Note |
---|
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.
Note |
---|
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
To place the phone call, the App uses the Unified API Create Simple PhoneCalls request. It uses the extension defined in the global variable VN_EXTENSION as the source of the call as in the example below. All fields are fictitious.
Code Block | ||
---|---|---|
| ||
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>/interface/plib/lib.php and is described below:
Code Block | ||||
---|---|---|---|---|
| ||||
// 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); |
The source and extension request parameters can be different as described in the Create Simple PhoneCalls recommendations. The CallMeButton App uses the same extension for both parameters.
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.
Code Block | ||
---|---|---|
| ||
GET /uapi/phoneCalls/@me/<VN_EXTENSION>/<phoneCallID> HOST x.x.x.x Content Type: application/json Authorization: <OAUTH_ACCESS_TOKEN> |
4psarelated | ||
---|---|---|
| ||
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.