Telephony Integration Tips

Bitrix24.Market

Mobile

Desktop

For Developers

Bitrix24.Market

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.

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!
Forget about OAuth!
Use password protected webhooks instead of tricky OAuth authentication.
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.