...
Excerpt |
---|
This page describes an App that uses UnifiedAPI to send faxes. Download. |
Table of Contents | ||
---|---|---|
|
Note | ||
---|---|---|
| ||
Download here. Do not hesitate to contribute if you want to improve this example - we welcome Pull Requests!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
Click2Fax is an App written in PHP that allows anyone to send faxes using the UnifiedAPI. It uses the Fax resource Fax resource exposed by Unified API and the following request:
- Create Faxes - Send fax to any number without need of approval
...
Installation
In order to be able to use the Click2Fax App, your system must be compliant with the requirement below:
- Your system needs to have PHP 5.3 installed or higher.
- Your VoipNow server must be at least version 3.0.0
- The extension should be able to send faxes.
Setup
STEP 1: Download the files.Download the archive, extract the files, and copy them to a Switch to the directory that can be accessed over the Web.web (e.g /var/www/html) and download the files.
Shell |
---|
git clone https://github.com/4psa/app-click2fax.git |
STEP 2: Proceed to allowing permissions and ownership rights.
You also need to give proper permissions and ownership right for the files of the plugin - the plugin needs to be owned by the web server user and group. For example, if we use httpd as a webserver:
Shell |
---|
chmod -R 755 <PATH_TO_Click2Fax> chown -R httpd:httpd <PATH_TO_Click2Fax> |
STEP 3: Configure the App.
In order to use the App, you you must configure it. To do so, you must open the file file config.php
in the in the <PATH_TO_Click2FAX>/interface/config/config.php
and and change 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. |
OAUTH_APP_ID | OAuth App ID or key. A 32 char-long string used by the App to identify itself with the system. Visit Check this page to see learn how to obtain 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 Check this page to see learn how to obtain 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. |
STEP 3: Proceed to allowing permissions and ownership rights.
You also need to give proper permissions and ownership to the files of the plugin - the plugin needs to be owned by the web server user and group. For example, if we use httpd as a webserver:
Code Block |
---|
chmod -R 755 <PATH_TO_Click2Fax>
chwon -R httpd:httpd <PATH_TO_Click2Fax>
|
STEP 4: Setup the system.
You also need to make sure the VoipNow system is setup set to receive faxes.
...
Behavior
User
...
interface
As soon as the setup process is complete, you can access the interface at https://<IP>/<PATH_TO_CLICK2FAX>/interface/.
The page displays a single button that the user can click in order to send the faxes. Once the button is clicked the following form appears:for sending faxes. Click this button and a form similar to the one below will be displayed.
To send the fax a user must enter the information , you must fill in the form fields as described below:following the explanations below.
Field name | Required | Description |
---|---|---|
To | Yes | A list of phone numbers separated by a comma. You can set here an a VoipNow extension from VoipNow that accepts faxes. |
Attachments | Yes | Choose a file to send as the fax body of the fax . |
After Once you have filled in the form is correctly filled, the user must click press the Send fax button to send the fax.
Internal
...
flow
When As soon as the Send Fax button fax button is pressed, the scripts makes sends a Create Faxes request to the VoipNow server using UnifiedAPIthroughUnifiedAPI. It It uses the extension defined in the global variable variable VN_EXTENSION as as the source of the fax call.
First it sets the HTTP headers and the Request body accordingly:
Code Block | ||
---|---|---|
| ||
// $token Fetch token $token = getToken= generateToken(); if (!$token) { return false; } $faxRequest = new FaxRequest(); $headers = $faxRequest->initHeaders(array( 'Authorization: ' =>. $token )); $request = new cURLRequest(); //Fax Create uses POST $request->setMethod(cURLRequest::METHOD_POST); $request->setHeaders($headers); $request->setBody(array('recipients' => array($_POST['to'])), cURLRequest::ENCODER_JSON); $params = array( 'recipients' => array($_POST['to']) ); //Set fax information (ex. recipients list) $this->_payload['request'] = json_encode($params); // Set uploaded files to send them by fax foreach ($files as $fileAlias => $fileInfo) { $this->_payload[$fileAlias] = new CURLFile($fileInfo['location'], $fileInfo['type'], $fileInfo['name']); } $response = $faxRequest->execute(); |
The The HTTP Request made by the App looks like this:
Code Block |
---|
POST /uapi/faxes/@me/0003*210 HTTP/1.1 HOST x.x.x.x Authorization: <OAUTH_ACCESS_TOKEN> Content-Length:469 Content-Type: multipart/form-data; boundary=------------325343636 ------------325343636-------- Content-Disposition:form-data; name="files"; filename="/path/to/file/file.ext" Content-Type;application/octet-stream This is my fax ------------325343636 Content-Disposition:form-data; name="request"; { "recipients":[<FAX_EXTENSION_TO>] } ------------325343636 |
Then sets the files which have which have been uploaded through the browser:
Code Block | ||
---|---|---|
| ||
$files = array(); $numberOfFiles = count($_FILES['attachments']['name']); $files = array(); forfor ($i = 0; $i < $numberOfFiles; $i++) { if ($_FILES['attachments']['error'][$i] > 0) { continue; } //Renaming the file including the extension $fileext = pathinfo( $files[$_FILES['attachments']['name'][$i]], PATHINFO_EXTENSION); move_uploaded_file( = array( 'location' => $_FILES['attachments']['tmp_name'][$i], 'type' => $_FILES['attachments']['tmp_nametype'][$i].'.'.$fileext); $files[] = array($_FILES['attachments']['name'][$i], 'name' => '@'.$_FILES['attachments']['tmp_name'][$i].'.'.$fileext ); } $request->setFiles($files); |
Any errors will be displayed on the browser.
Note | |||||
---|---|---|---|---|---|
Your Voipnow SSL certificate should be signed by a trusted certificate authority, otherwise the Click2Fax application will not be able to communicate safely with the server. You can use a self-signed certificate, but we do not recommend this on a production server. For testing purposes only, you may add the following line into the generateToken() function available in /plib/util/.
|
4psarelated | ||
---|---|---|
| ||
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.