Page Comparison

Html

 <div class="lang-box-pdf">
	<div>
		<div class="google-lang">
			<div id="google_translate_element">
			</div>
			<script type="text/javascript">
					function googleTranslateElementInit() {
						new google.translate.TranslateElement({pageLanguage: 'en', includedLanguages: 'de,es,fr,it,nl', autoDisplay: false}, 'google_translate_element');
						}
			</script>
			<script type="text/javascript" src="//translate.google.com/translate_a/element.js?cb=googleTranslateElementInit"></script>
		</div>
		
		<div class="pdf-button">
			<a href="https://confluence.wildix.com/spaces/flyingpdf/pdfpageexport.action?pageId=77988609" alt="Convert to .pdf" title="Convert to .pdf"><img src="https://confluence.wildix.com/download/attachments/14549012/pdf-button-download-wildix-documentation.png"></a>
		</div>
	</div>
</div>

Info

The article describes how to use the new authentication method to make WMS API requests.

Created: September 2020

Permalink: https://confluence.wildix.com/x/AQOmB

Table of Contents

Introduction

The authentication method described in this article is recommended to be used for admin user API authentication on the Wildix systems running WMS 5 or higher.

Every request made to WMS API needs to have the following headers:

Host - domain to which the API request is sent

Authorization - contains the JWT token with the necessary data and signature

X-APP-ID - API ID obtained from WMS or API

You can find the documentation regarding the new Authentication mechanism in your system (logged in as admin): https://SYSTEM-NAME.wildixin.com/api/v1/doc/#section/Authentication.

However, to simplify your development, there is Wildix php library that you can use which handles all the process for authentication. Besides the mentioned php library, a tool for dependency management in php called composer will also be used here. Neither s2s-client-php nor composer are mandatory when trying to use Wildix API, but here they are used to show a basic working example. In a php environment they make it easier to consume Wildix APIs but any language/ environment that can implement JWT tokens can be used for your development.

Installation

1. A server with apache2 and php installed is assumed. First, install required dependencies:

Code Block
$apt-get install wget php-cli php-zip unzip curl php-curl

2. Then proceed to installing composer:

Code Block
$curl -sS https://getcomposer.org/installer \|php

3. Next move composer to /usr/bin folder to make it available system wide:

Code Block
$sudo mv composer.phar /usr/bin/composer

4. Now proceed to installing the s2s-client-php library. Get the library from git (https://github.com/Wildix/s2s-client-php). You can do this by either cloning the project or downloading the zip file. For simplicity here, we download the zip file:

Code Block
$wget https://github.com/Wildix/s2s-client-php/archive/master.zip $unzip master.zip

5. Next create a folder for the project on your web server and create a Wildix folder to store the downloaded files:

Code Block
$sudo mkdir /var/www/html/project $sudo mkdir /var/www/html/project/wildix

6. Move the uncompressed folder to Wildix folder:

Code Block
$sudo mv s2s-client-php-master /var/www/html/project/wildix/

7. Next, run the following command (from your project folder):

Code Block
$sudo composer require wildix/s2s-client-php

After running the command above you should have a composer.json file and a vendor folder inside your project folder as shown below:

Once you have both the json file and the vendor folder you can use the library on your scripts.

Note
Note: if the following error message appears in the previous step: The "https://repo.packagist.org/packages.json" file could not be downloaded: failed to open stream: Connection timed out, use a work around described below.

You can use a work around. Simply create an entry (as root) in your hosts file for the domain name and ip address:

Code Block
$dig +short repo.packagist.org $echo '142.44.164.249 repo.packagist.org' >> /etc/hosts

Consuming the Wildix API

First, you need to create an “Application ID” and a secret for your application. In WMS (logged in as admin) go to PBX -> Integrations-> Server to Server applications and click Add:

In the displayed form, assign a name and a user (ACL rules apply to selected user) to your application:

Once created, both the “Application ID” and the secret are shown:

The values shown are available at any time by clicking the eye icon on the corresponding application:

Now create php scripts to consume the application.

CallQueues

This first example will consume API “Call Queues” (Get a list of call Queues):

https://SYSTEM-NAME.wildixin.com/api/v1/doc/#operation/pbxSettingsGetCallQueues.

1. Create a php file (in this case group.php) on your project folder and add the following content:

Add needed library:

Code Block
require_once 'vendor/autoload.php';

Then create the client instance:

Required values are found on PBX -> Integrations-> Server to Server applications. Your script should look something like this:

...

Scroll export button

scope	current
template-id	0fa09813-8b86-460a-aa1d-ef450a80e9ce
quick-start	true
add-on	Scroll PDF Exporter

Info

The Articles describes how to use S2S authentication method to make WMS API requests.

Created: September 2020

Updated: January 2023

Permalink: https://wildix.atlassian.net/wiki/x/oBPOAQ

Table of Contents

Introduction

Below is an example of Basic API authentication for the admin user (note the -u ‘admin’:’blurred password’):

Image Added

However, the recommended authentication mechanism for the admin user on Wildix systems running WMS 5 or higher is S2S authentication using the PHP HTTP client library. In this article, we will see in detail how to use this authentication mechanism for API requests.

Every request made to WMS API needs to have the following headers:

Host - domain to which the API request is sent

Authorization - contains the JWT token with the necessary data and signature

X-APP-ID - API ID obtained from WMS or API

You can find the documentation regarding the Authentication mechanism in your system (logged in as admin): https://SYSTEM-NAME.wildixin.com/api/v1/doc/#section/Authentication.

However, to simplify your development, there is Wildix php library that you can use which handles all the process for authentication. Besides the mentioned php library, a tool for dependency management in php called composer will also be used here. Neither s2s-client-php nor composer are mandatory when trying to use Wildix API, but here they are used to show a basic working example. In a php environment they make it easier to consume Wildix APIs but any language/ environment that can implement JWT tokens can be used for your development.

Installation

1. A server with apache2 and php installed is assumed. First, install required dependencies:

Code Block
$apt-get install wget php-cli php-zip unzip curl php-curl

2. Then proceed to installing composer:

Image Added

Code Block
$curl -sS https://getcomposer.org/installer \|php

3. Next move composer to /usr/bin folder to make it available system wide:

Code Block
$sudo mv composer.phar /usr/bin/composer

4. Now proceed to installing the s2s-client-php library. Get the library from git (https://github.com/Wildix/s2s-client-php). You can do this by either cloning the project or downloading the zip file. For simplicity here, we download the zip file:

Code Block
$wget https://github.com/Wildix/s2s-client-php/archive/master.zip $unzip master.zip

5. Next create a folder for the project on your web server and create a Wildix folder to store the downloaded files:

Code Block
$sudo mkdir /var/www/html/project $sudo mkdir /var/www/html/project/wildix

6. Move the uncompressed folder to Wildix folder:

Code Block
$sudo mv s2s-client-php-master /var/www/html/project/wildix/

7. Next, run the following command (from your project folder):

Image Added

Code Block
$sudo composer require wildix/s2s-client-php

After running the command above you should have a composer.json file and a vendor folder inside your project folder as shown below:

Image Added

Once you have both the json file and the vendor folder you can use the library on your scripts.

Note
Note: if the following error message appears in the previous step: The "https://repo.packagist.org/packages.json" file could not be downloaded: failed to open stream: Connection timed out, use a work around described below.

Image Added

You can use a work around. Simply create an entry (as root) in your hosts file for the domain name and ip address:

Image Added

Code Block
$dig +short repo.packagist.org $echo '142.44.164.249 repo.packagist.org' >> /etc/hosts

Consuming the Wildix API

First, you need to create an “Application ID” and a secret for your application. In WMS (logged in as admin) go to PBX -> Integrations-> Server to Server applications and click Add:

Image Added

In the displayed form, assign a name and a user (ACL rules apply to selected user) to your application:

Image Added

Once created, both the “Application ID” and the secret are shown:

Image Added

The values shown are available at any time by clicking the eye icon on the corresponding application:

Image Added

Now create php scripts to consume the application.

CallQueues

This first example will consume API “Call Queues” (Get a list of call Queues):

Image Added

https://SYSTEM-NAME.wildixin.com/api/v1/doc/#operation/pbxSettingsGetCallQueues.

1. Create a php file (in this case group.php) on your project folder and add the following content:

Add needed library:

Image Added

Code Block
require_once 'vendor/autoload.php';

Then create the client instance:
Image Added

Required values are found on PBX -> Integrations-> Server to Server applications. Your script should look something like this:

Image Added

Code Block
$config = [ 'host' => 'https://SYSTEM-NAME.wildixin.com', 'app_id' => 'APP_ID', 'secret_key' => 'SECRETKEY', 'app_name' => 'APP NAME', ]; $client = new Wildix\Integrations\Client($config, []);

...

2. Next we need to configure parameters. Since the CallQueues API is a GET request and does not require any parameters, the options should look something like this:

Image Added

Code Block
$options = [ 'params' => [ ], 'body' => [ ], 'headers' => [ ] ];

...

3. Finally, we need to make the request. Since CallQueues requires a GET request we’ll use that method:

Image Added

Code Block
$response = $client->get('api/v1/PBX/settings/CallQueues/', $options);

...

5. Now to show the response:

Image Added

Code Block

echo $response->getStatusCode(); // 200
echo $response->getHeaderLine('content-type'); // 'application/json; charset=utf8'
echo $response->getBody()->getContents(); // '{"type": "result", "result": {}}'

...

The following is the entire script:

Image Added

Note
Note: in the previous picture that the status code and headers responses were commented in order to be able to format the entire output as json, see next image.

When the script is run:

Image Added

CallHistory

For this example we will consume API “CallHistory” (Get a global call history):

Image Added

https://SYSTEM-NAME.wildixin.com/api/v1/doc/#tag/Call-History.

1. Create a php file (in this case callhistory.php) in your project folder and add the following content:

Add needed library:

Image Added

Code Block
require_once 'vendor/autoload.php';

...

Then create the client instance:

Image Added

Required values are found on PBX -> Integrations-> Server to Server applications. Your script should look something like this:

Image Added

Code Block
$config = [ 'host' => 'https://SYSTEM-NAME.wildixin.com', 'app_id' => 'APP_ID', 'secret_key' => 'SECRETKEY', 'app_name' => 'APP NAME', ]; $client = new Wildix\Integrations\Client($config, []);

...

2. Next, configure the parameters. Since the CallHistory API needs a GET request with parameters, we need to add them in ‘params’ section as shown below:

Image Added

Code Block

$fields = 'id,start,end,src,dst';
$filter = [
        'start'=>[
                'from'=>'02/06/2020 00:01',
                'to'=>'02/06/2020 23:59'
        ],
];
$options = [
        'params' => [
                'fields'=>$fields,
                'filter'=>$filter
        ],
    'body' => [
    ],
    'headers' => [
    ]
];

...

3. Finally we just need to make the request and get the response:

Image Added

Code Block

$response = $client->get('api/v1/PBX/CallHistory/', $options);
//echo $response->getStatusCode(); // 200
//echo $response->getHeaderLine('content-type'); // 'application/json; charset=utf8'
echo $response->getBody()->getContents(); // '{"type": "result", "result": {}}'
?>

The entire script:

Image Added

Note
Note: in the previous picture the status code and headers responses were commented in order to be able to format the entire output as json. See the next image.

When the script is run:

Image Added

Sounds

For this example we will consume API “Sounds” (Create or update sound.):

Image Added

https://SYSTEM-NAME.wildixin.com/api/v1/doc/#operation/SoundsCreate.

1. Create a php file (in this case sounds.php) in your project folder and add the following content:

Add needed library:

Image Added

Code Block
require_once 'vendor/autoload.php';

...

Then create the client instance:

Image Added

The required values are found on PBX -> Integrations -> Server to Server applications. Your script should look something like this:

Image Added

Code Block
$config = [ 'host' => 'https://SYSTEM-NAME.wildixin.com', 'app_id' => 'APP_ID', 'secret_key' => 'SECRETKEY', 'app_name' => 'APP NAME', ]; $client = new Wildix\Integrations\Client($config, []);

...

2. Next we need to configure parameters. Since the Sounds API needs a POST request with parameters, we need to add them in the body section:

Image Added

Code Block

$filename = 'testfromAPI';
$directory = '';
$text = 'this is a test from Sounds API';
$voice = 'Kimberly';
$options = [
        'params' => [
        ],
        'body' => [
                'directory'=>$directory,
                'filename'=>$filename,
                'text'=>$text,
                'voice'=>$voice
    ],
    'headers' => [
//          'content-type' => 'multipart/form-data'
    ]
];

...

Finally we just need to make the request using post method and get the response:

Image Added

Code Block

$response = $client->post('api/v1/Sounds/', $options);
//echo $response->getStatusCode(); // 200
//echo $response->getHeaderLine('content-type'); // 'application/json; charset=utf8'
echo $response->getBody()->getContents(); // '{"type": "result", "result": {}}'
?>

The entire script:

Image Added

Note
Note: in the previous picture the status code and headers responses were commented in order to be able to format the entire output as json, see next image.

When the script is run:

Image Added

And in WMS sounds:

Image Added

Originate

For this example we will consume API “Originate” (used to create new calls):

...

1. Create a php file (in this case originate.php) in your project folder and add the following content:

Add needed library:

Image Added

Code Block
require_once 'vendor/autoload.php';

...

Then create the client instance:

Image Added

Required values are found on PBX -> Integrations -> Server to Server applications. Your script should look something like this:

Image Added

Code Block
$config = [ 'host' => 'https://SYSTEM-NAME.wildixin.com', 'app_id' => 'APP_ID', 'secret_key' => 'SECRETKEY', 'app_name' => 'APP NAME', ]; $client = new Wildix\Integrations\Client($config, []);

...

2. Next we need to configure parameters. Since Originate API needs a POST request with parameters, we need to add them in body section:

Image Added

Code Block

$chan = 'Local/108@users';
$context = 'users';
$exten = '16144841500';
$priority = '1';
$callerid = "\"Announcer\" <16144841500>";
$options = [
        'params' => [
        ],
        'body' => [
                'callerid'=>$callerid,
                'channel'=>$chan,
                'context'=>$context,
                'exten'=>$exten,
                'priority'=>$priority
        ],
        'headers' => [
    ]
];

...

In the previous picture, first we create variables for needed parameters. In this example we will call extension 108. If extension 108 picks up the call we will dial the number 16144841500). Then we refer to those variables in the body section (for POST requests body section is used). It is worth mentioning that all parameters need to be ordered alphabetically and parameter names can only be lowercase.

Finally we just need to make the request and get the response:

Code Block

$response = $client->post("/api/v1/Originate/", $options);
//echo $response->getStatusCode(); // 200
//echo $response->getHeaderLine('content-type'); // 'application/json; charset=utf8'
echo $response->getBody()->getContents(); // '{"type": "result", "result": {}}'
?>

The entire script:

Note
Note: in the previous picture the status code and headers responses were commented in order to be able to format the entire output as json, see next image.

When the script is run:

In user 108 Collaboration:

When the call is answered:

...

worth mentioning that all parameters need to be ordered alphabetically and parameter names can only be lowercase.

Finally we just need to make the request and get the response:

Image Added

Code Block

$response = $client->post("/api/v1/Originate/", $options);
//echo $response->getStatusCode(); // 200
//echo $response->getHeaderLine('content-type'); // 'application/json; charset=utf8'
echo $response->getBody()->getContents(); // '{"type": "result", "result": {}}'
?>

The entire script:

Image Added

Note
Note: in the previous picture the status code and headers responses were commented in order to be able to format the entire output as json, see next image.

When the script is run:

Image Added

In user 108 Collaboration:

Image Added

When the call is answered:

Image Added

Macrosuite divider macro

dividerType	text
dividerWidth	70
emoji	{"id":"smile","name":"Smiling Face with Open Mouth and Smiling Eyes","short_names":["smile"],"colons":":smile:","emoticons":["C:","c:",":D",":-D"],"unified":"1f604","skin":null,"native":"😄"}
textColor	#000000
dividerWeight	2
labelPosition	middle
textAlignment	center
iconColor	#0052CC
fontSize	medium
text	Not finding the help you need? Join the Facebook group to ask a question!
emojiEnabled	false
dividerColor	#DFE1E6
dividerIcon	bootstrap/CloudsFill

Button macro

buttonText	Facebook
isButtonShadowOn	true
emoji	{"id":"smile","name":"Smiling Face with Open Mouth and Smiling Eyes","short_names":["smile"],"colons":":smile:","emoticons":["C:","c:",":D",":-D"],"unified":"1f604","skin":null,"native":"😄"}
buttonBorderColor	#4267b2ff
buttonColor	#4267b2ff
buttonNewTab	false
buttonFontColor	#ffffff
buttonSize	medium
buttonIconColor	#ffffff
buttonWidthDetection	46
buttonHoverColor	#ffffff
buttonIcon	font-awesome/FacebookSquare
buttonType	icon_left
buttonLink	{"link":"https://www.facebook.com/groups/wildixtechwizards","source":"direct"}
buttonNewLink
buttonRadius	3
buttonShadow	0
id	228
emojiEnabled	false
buttonWidth	20

Versions Compared

Old Version 5

New Version Current

Key

Introduction

Installation

Consuming the Wildix API

CallQueues

Introduction

Installation

Consuming the Wildix API

CallQueues

CallHistory

Sounds

Originate