Telephony Integration Tips

Use the new Telephony REST API to implement any real world scenario

  • Conversation with a Client
    Show the call details form to a sales representative in charge of this client.
  • Call Processing Queue
    Process inbound calls in simultaneous or sequential manner.
  • Group Communication
    Redirect the call to a different employee who can help.
  • Call Recordings and Reports
    Save a call recording to the CRM and standard reports.

Full Integration is Only Three Steps Away!

We have done our best to make integration as simple as possible.

  1. Only Four REST Methods
    The new telephony API includes only four methods and one event! You will get completely comfortable with it in under 15 minutes!
  2. Forget about OAuth!
    Use password protected webhooks instead of tricky OAuth authentication.
  3. Implement Any Scenario
    Improve the implementation of your telephony integration and make it more sophisticated.

How to Connect an Inbound Call to Bitrix24?

Common Integration Approach

  • Only one REST API Method
    Create an inbound webhook for use with the telephony.externalcall.register method.
  • Developer Hints
    When creating a webhook, Bitrix24 will suggest the required parameters and generate a ready to roll URL to be called from your telephony system.
  • Create a New Lead
    If an inbound phone number does not exist in the CRM, Bitrix24 will create a lead and return the new lead's ID.
  • Search the CRM for Existing Clients
    If there is a match among leads, contacts or companies existing in the CRM, the method will return an appropriate result.
<?php

$queryUrl = 'https://xxx.bitrix24.com/rest/1/yyyyxxx000111/telephony.externalcall.register.json';
$queryData = http_build_query(array(
'USER_ID' => 1,
'PHONE_NUMBER' => '555666777',
'TYPE' => 2,
'CALL_START_DATE' => '2016-16-11 10:10',
'CRM_CREATE' => true
));

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POST => 1,
CURLOPT_HEADER => 0,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => $queryUrl,
CURLOPT_POSTFIELDS => $queryData,
));

$result = curl_exec($curl);
curl_close($curl);

$result = json_decode($result, 1);

How to Reconcile Your Processing Queue with Bitrix24?

Use any queue logic!

  • Only Two REST API Methods
    Create inbound webhooks for use with the telephony.externalcall.show and telephony.externalcall.hide methods.
  • Arbitrary Queue Processing Algorithm
    Show call details to required persons simultaneously or according to the queue by calling the telephony.externalcall.show webhook; hide the details form when it is no longer needed by using the telephony.externalcall.hide.
<?php

$queryUrl = 'https://xxx.bitrix24.com/rest/1/yyyyxxx000111/telephony.externalcall.hide.json';
$queryData = http_build_query(array(
'CALL_ID' => 'externalCall.a2fc40b56aa869141cc6aa2d2a965ba6.1478527542', // from telephony.externalcall.register
'USER_ID' => 1 // hide the call details form from user 1's screen
));

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POST => 1,
CURLOPT_HEADER => 0,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => $queryUrl,
CURLOPT_POSTFIELDS => $queryData,
));

$result = curl_exec($curl);
curl_close($curl);

$queryUrl = 'https://xxx.bitrix24.com/rest/1/yyyyxxx000111/telephony.externalcall.show.json';
$queryData = http_build_query(array(
'CALL_ID' => 'externalCall.a2fc40b56aa869141cc6aa2d2a965ba6.1478527542', // from telephony.externalcall.register,
'USER_ID' => 6 // show the call details form to user 6
));

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POST => 1,
CURLOPT_HEADER => 0,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => $queryUrl,
CURLOPT_POSTFIELDS => $queryData,
));

$result = curl_exec($curl);
curl_close($curl);

How Can a User Call from Bitrix24?

Direct Calls from the CRM!

  • Only One REST API Method
    Create an inbound webhook for the OnExternalCallStart event.
  • A User Initiates a Call from Bitrix24
    When a user clicks the client's phone number in Bitrix24, the webhook will relay the outbound phone number to your PBX.
  • Make the Call!
    Now all you have to do is start the call on your PBX!
specify your handler's URL in the outbound webhook preferences
https://your_server/your_webhook_script.php


handler code
<?php

/*

Bitrix24 passes $_REQUEST to the handler containing the following data:

array(
'PHONE_NUMBER' => '555666777', // number to dial
'USER_ID' => '1', // the ID of a user initiating the call
'CRM_ENTITY_TYPE' => 'LEAD', // type of a CRM object whose details form the user opened to make the call
'CRM_ENTITY_ID' => '248' // the ID of the respective CRM entity
)
*/

// register the outbound call
$queryUrl = 'https://xxx.bitrix24.com/rest/1/yyyyxxx000111/telephony.externalcall.register.json';
$queryData = http_build_query(array(
'USER_ID' => $_REQUEST['USER_ID'],
'PHONE_NUMBER' => $_REQUEST['USER_ID'],
'TYPE' => 1, // outbound call
'CALL_START_DATE' => '2016-16-11 10:10',
'CRM_CREATE' => false,
'CRM_ENTITY_TYPE' => $_REQUEST['CRM_ENTITY_TYPE'],
'CRM_ENTITY_ID' => $_REQUEST['CRM_ENTITY_ID']
));

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POST => 1,
CURLOPT_HEADER => 0,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => $queryUrl,
CURLOPT_POSTFIELDS => $queryData,
));

$result = curl_exec($curl);
curl_close($curl);

$result = json_decode($result, 1);

How to Save the Call Recording to Bitrix24?

View the details and listen to the call recording without leaving the CRM!

  • Only One REST API Method
    Add an outbound webhook for use with the telephony.externalcall.finish method.
  • Add the Recording
    Once the call has been completed, call the webhook specifying the call parameters: length and status.
  • Keep and Listen to Call Recordings in Bitrix24
    Provide a link to the call recording to have Bitrix24 uploaded it to CRM!
  • Standard Telephony Reports
    Highlight call fees to make calls more efficient!
<?php

$queryUrl = 'https://xxx.bitrix24.com/rest/1/yyyyxxx000111/telephony.externalcall.finish.json';
$queryData = http_build_query(array(
'CALL_ID' => 'externalCall.733e885003cbac98d92b811806caeaea.1478528885', // from telephony.externalcall.register
'DURATION' => '120', // call length, seconds
'STATUS_CODE' => 200, // status: success
'RECORD_URL' => 'http://your_server/call_record.mp3', // save call recording from this URL
));

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POST => 1,
CURLOPT_HEADER => 0,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => $queryUrl,
CURLOPT_POSTFIELDS => $queryData,
));

$result = curl_exec($curl);
curl_close($curl);

$result = json_decode($result, 1);

Need something beyond webhook capabilities?

Read to the documentation and view an example of a local application.