Wat kan ik hier?

Klik-en-bel is één van de beschikbare API's van het platform. Met klik-en-bel kan geautomatiseerd een gesprek worden opgezet tussen twee telefoonnummers.

Deze API communiceert in JSON. De API wordt onder andere gebruikt door onze eigen klik-en-bel browser plug-ins (beschikbaar in de web stores voor Google Chrome en Mozilla Firefox), maar je kunt ook zelf code schrijven om gebruik te maken van de klik-en-bel functionaliteit.

Wanneer je een gesprek start via klik-en-bel wordt de geselecteerde eindbestemming van de gebruiker gebeld en zodra je het gesprek aanneemt ook het opgegeven telefoonnummer.

Wie kan klik-en-bel gebruiken?

Elke gebruiker die een eindbestemming kan kiezen, heeft toegang tot de klik-en-bel API. Authenticatie gebeurt met gebruikersnaam en wachtwoord. Een voorbeeld hiervan is verder in dit artikel te vinden voor PHP. Een partnergebruiker (een account dat klanten kan beheren) valt hier dus niet onder!

Voorbeeldgebruik van de API (PHP)

De authenticatie gebeurt via een HTTP header en bestaat uit een base64-encoded tekenreeks die opgebouwd is op basis van de gebruikersnaam en het wachtwoord van de eindgebruiker. Deze tekenreeks kun je snel op twee manieren berekenen.

localhost:~ $ echo -n "gebruikersnaam:wachtwoord" | base64
Z2VicnVpa2Vyc25hYW06d2FjaHR3b29yZA==

De tweede regel is de output van het base64-command. In het PHP voorbeeld kan je zien hoe deze waarde wordt gebruikt.

Als je geen toegang hebt tot een shell met het base64-command kan je de base64-encoded tekenreeks ook met PHP zelf genereren. Met onderstaande code in een php-bestand genaamd "base64.php" kan je het genereren met:

localhost:~ $ php base64.php gebruikersnaam wachtwoord
Z2VicnVpa2Vyc25hYW06d2FjaHR3b29yZA==

De tweede regel is de output van het php-bestand. In het PHP voorbeeld verderop kan je zien hoe deze waarde wordt gebruikt.

De source code van "base64.php":

<?php
| /**
* Generate a base64-encoded string based on parameters
* provided via the command line or the query string.
*/
| $username = $password = null;
| /* read command line arguments */
if(count($argv) > 1) {
$username = $argv[1];
$password = $argv[2];
}
| /* or read query string arguments */
if(isset($_GET['username']) && isset($_GET['password'])) {
$username = $_GET['username'];
$password = $_GET['password'];
}
| /* generate base64 string */
$base64 = base64_encode("{$username}:${password}");
print $base64 . PHP_EOL;

Bovenstaande script kan je ook aanroepen in je browser door de url in te typen naar dit PHP bestand en de gebruikersnaam en wachtwoord toe te voegen aan de URL (let wel dat dit problemen kan opleveren als je speciale karakters gebruikt in je wachtwoorden en daarom niet wordt aangeraden):

?username=gebruikersnaam&password=wachtwoord

Na het genereren kan je de waarde gebruiken in onderstaande script:

<?php
| /**
* Prepare parameters.
*/
| /* dial this number using the API */
$number_to_call = '+31508009899';
| /* parameters for the API call */
$post_fields = json_encode(array(
// optional, which extension should initiate the call.
// We look at the users click to dial extension setting to set up the call from. But if this is not desired you can put the a-number here.
// 'a_number' => '202',
| // required, number or extension to dial
'b_number' => $number_to_call,
|
// optional, the number side B sees on the incoming call
// must be a number you own, or you can select 'default_number'. In this case the first number in the phonenumberlist will be chosen.
'b_cli' => '',
| // optional, whether or not to answer the incoming call to your own phone automatically
// must be true or false - if not provided it will use the user's preference
'auto_answer' => '',
));
| $authentication_header = 'Authorization: Basic Z2VicnVpa2Vyc25hYW06d2FjaHR3b29yZA==';
$http_headers = array(
// tell the API we provide JSON data
'Content-Type: application/json',
'Content-Length: ' . strlen($post_fields),
| // tell the API we want JSON data
'Accept: application/json',
| // authenticate using the string created earlier
$authentication_header,
);
| /**
* Use cURL to make a HTTP request.
*/
| /* create a new cURL resource */
$ch = curl_init();
| /* set URL and other appropriate options */
curl_setopt_array($ch, array(
CURLOPT_POSTFIELDS => $post_fields,
CURLOPT_HTTPHEADER => $http_headers,
CURLOPT_URL => 'https://api.voipgrid.nl/api/clicktodial/',
CURLOPT_RETURNTRANSFER => true,
));
| /* send the data and receive the response */
$response = curl_exec($ch);
| /* read callid from the response data */
/* $callid can be used to track the status of a call */
$callid = json_decode($response)->callid;
print $callid . PHP_EOL;
| /* close cURL resource, and free up system resources */
curl_close($ch);

Debuggen van de API (PHP)

Voeg dit toe aan het begin van het script onder de php-openingstag.

ini_set('display_errors', 1);
error_reporting(E_ALL);

Mocht er geen output verschijnen, dan kan kan dit worden veroorzaakt door een parse error, dan is het nodig om display_errors in te stellen in het php.ini configuratiebestand.

Vervang het laatste gedeelte van het script met onderstaande. Zorg ervoor dat $log_filename een geldig pad bevat waar het php-process naar kan schrijven.

/**
* Use cURL to make a HTTP request.
*/
| /* create a new cURL resource */
$ch = curl_init();
| /* write to this file, overwriting every request */
$log_filename = '/tmp/curl.log';
$curl_log = fopen($log_filename, 'wa+');
| /* set URL and other appropriate options */
curl_setopt_array($ch, array(
CURLOPT_POSTFIELDS => $post_fields,
CURLOPT_HTTPHEADER => $http_headers,
CURLOPT_URL => $DOMAIN . '/api/clicktodial/',
CURLOPT_RETURNTRANSFER => true,
| /* extra debug options */
CURLOPT_CERTINFO => true,
CURLOPT_HEADER => true,
CURLOPT_STDERR => $curl_log,
CURLOPT_VERBOSE => true,
));
| /* send the data and receive the response */
$response = curl_exec($ch);
| /* with CURLOPT_HEADER it is necessary to split headers and body */
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
| $body = substr($response, $header_size);
| /* read curl verbose output from file */
rewind($curl_log);
print '<h1>CURL</h1> <pre>' . print_r(fread($curl_log, filesize($log_filename)), 1) . '</pre>';
| /* append response to file to make the file log complete for this request */
fwrite($curl_log, $response);
fclose($curl_log);
| print '<h1>response headers</h1> <pre>' . $header . '</pre>';
| print '<h1>response body</h1> <pre>' . $body . '</pre>';
| /* if any curl errors, throw an exception */
if (FALSE === $response) {
throw new Exception(curl_error($ch), curl_errno($ch));
}
| /* read callid from the response data */
/* $callid can be used to track the status of a call */
$callid = json_decode($body)->callid;
print '<h1>callid from body</h1> <pre>' . $callid . '</pre>';
| /* close cURL resource, and free up system resources */
curl_close($ch);

Gespreksstatus

Zoals misschien opgemerkt in bovenstaand script geeft de API ook een response. Het call id uit deze response is te gebruiken om de status van het zojuist opgezette gesprek te volgen door een nieuwe aanroep te doen (bijvoorbeeld met cURL). In de response zelf staat ook een status, maar deze kan leeg zijn, omdat het gesprek a-synchroom opgezet wordt. De code voor de status api-call is simpeler, er hoeft namelijk alleen maar een GET HTTP request gedaan te worden. Een voorbeeld hiervan is:

<?php
| /* Query the status for the call with this id */
$callid = '3asdf804d8d225db16a343347e8b4c3ce355c';
| $authentication_header = 'Authorization: Basic Z2VicnVpa2Vyc25hYW06d2FjaHR3b29yZA==';
$http_headers = array(
// tell the API we provide JSON data
'Content-Type: application/json',
| // tell the API we want JSON data
'Accept: application/json',
| // authenticate using the string created earlier
$authentication_header,
);
| /**
* Use cURL to make a HTTP request.
*/
| /* create a new cURL resource */
$ch = curl_init();
| /* set URL and other appropriate options */
curl_setopt_array($ch, array(
CURLOPT_HTTPHEADER => $http_headers,
CURLOPT_URL => sprintf('https://api.voipgrid.nl/api/clicktodial/%s/', $callid),
CURLOPT_RETURNTRANSFER => true,
));
| /* send the data and receive the response */
$response = curl_exec($ch);
| /* read status from the response data */
$status = json_decode($response)->status;
print $status . PHP_EOL;
| /* close cURL resource, and free up system resources */
curl_close($ch);

Mogelijke waarden voor het veld "status" zijn:

null, dit is soms mogelijk als het gesprek nog opgezet moet worden (de klik-en-bel API is asynchroon).
dialing_a, het platform maakt verbinding met de eindbestemming van de gebruiker.
dialing_b, het platform belt nu het gekozen nummer.
connected, het gesprek is tot stand gebracht.
disconnected, het gesprek is afgebroken.
failing_a, er kon geen verbinding worden opgezet met de eindbestemming van de gebruiker.
failing_b, er kon geen verbinding worden opgezet met het gekozen nummer.

Bijgewerkt op: 23/01/2023