Klik en Bel API

Uit Help
Ga naar:navigatie, zoeken

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 API-token. Je kunt je eigen API-token is terug rechtsboven in de portal onder Persoonlijk > Persoonlijke instellingen.

Ctd settings.png

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)

<?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: Token E-mailadres:API-token';
$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: Token E-mailadres:API-token';
$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.
;