Why do you need to integrate your own CRM/ERP/Desk with PBX
Most systems for business (CRM/ERP/Desk etc.) automate communication with clients and/or partners. While a significant part of communication is handled over the phone, the system simply has to be integrated with IP-telephony.
Especially for CRM/Desk and other automation system developers we are offering a manual for integrating your system with Zadarma IP-telephony.
Advantages of integrating with Zadarma:
- large Zadarma client database (over 2 million) will get an access to your services;
- your clients can integrate telephony at no expenses (PBX, API, integrations are free);
- worldwide coverage, your clients can be anywhere in the world (support in 7 languages, data centers on three continents, virtual numbers in 100 countries).
Also, after the integration, if your website is visited by over 30 thousand users a month, we are ready to test your integration and place the instruction on our website (what will give you access to free traffic from top VoIP providers in Europe).
In the personal account by this link there are direct integrations available (developed by us) with various systems, as well as in the section Help – Setup manual you can find integrations with third-party systems developed without our input. Open API allows to fulfill a complete integration with Zadarma virtual PBX, this can be accomplished by any developer due to a low level of difficulty. For efficiency, we will take a look at the integration of virtual Zadarma PBX and a third-part CRM.
Main features:
- Calls in one click from the CRM interface.
- Pop-up notifications about incoming/outgoing calls with information about the caller and a link to the caller’s card.
- Call statistics, call recordings in the client’s card.
- Automatic contacts/leads/deals creation during a call from a new client.
- Automatic incoming call routing to the responsible manager.
- Client name display on your IP-phone during an incoming call.
- Notifications about missed calls.
- A curated blacklist for incoming calls.
- Adding integration to Zadarma personal account.
Interaction with API can be conditionally divided into two parts:
1. Requests (POST, GET) from CRM side to API Zadarma
2. System of call notifications (webhook), POST-requests with information regarding calls send by our API to CRM
The full API documentation can be found here.
1. Integration setup on Zadarma side
Conditions necessary to start the integration:
In Zadarma personal account:
1. API authorization keys are generated (Key and Secret)
2. Virtual PBX is created and Setup wizard completed (PBX extension lines with call recording according to the number of CRM users, incoming calls scenario)
We have a Zadarma account and a certain CRM, which has a URL address for telephony module, for example:
https://mybestcrm.com/zadarma
or
https://id12345678.mybestcrm.com/zadarma
Further we will use this link as an example https://mybestcrm.com/zadarma (You need to have a link indicating your CRM)
In Zadarma personal account in section Settings – API in the column “Notify me and send the data in the following events:” all types of notifications have to be checked. In the section “Call notifications to the PBX” in the field “Link to your website” enter your CRM’s URL, the notifications about calls will be sent to this address.
In order for the system to accept the link, it is necessary to add a verification code at the beginning of the script.
Example for PHP:
<?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>
Link validation occurs after clicking the “Add” button, a random collection of symbols is sent to the link, for example, 1234567. According to the code above the link has to send back the value without additional symbols, spaces, BOM sequences, etc. If the link doesn’t go through validation, check what value is returned and send a curl request to your link adding to it ?zd_echo=1234567
curl https://mybestcrm.com/zadarma?zd_echo=1234567
The link has to return the value 1234567.
If it is empty or has a value different from 1234567 – validation was not successful.
To increase security, we recommend you to allow access to your link only from IP 185.45.152.42 In each request to your link you will receive and additional title "Signature", which can also be used to check data integrity and authenticity. More on that here.
2. Integration setup on the CRM side
In Zadarma personal account you already have a validated link to the CRM that will receive call notifications, and authorization keys created, now these keys have to be saved in CRM. On CRM side there should be a page for integration setup, let’s call it “Telephony settings”, this page has to have the following main parameters:
- Fields for keys authorization (Key and Secret).
- Link to telephony module in CRM, which we have been validating before https://mybestcrm.com/zadarma.
- A list of users with an option to set a unique PBX extension number for each of them.
A list of extension numbers can be obtained using method GET /v1/pbx/internal/
From the received list of extension numbers we form a contextual menu for assigning and extension number to each CRM user. If an extension number is already assigned to a user, it cannot be available for choosing or assigned to another user.
We recommend making one of the users responsible by default, by creating an appropriate checkbox on the telephony setup page. Responsible by default is an employee that will be automatically appointed for events that do not have a clearly assigned manager. For example, an incoming call from a new client is simultaneously directed to 5 extension numbers (5 CRM users) and if none of them picks up, we don’t want to lose a client. For such situation an event should be created in CRM where a “Missed call from number” task or lead is added, but if it is assigned to all 5 users, the client will receive 5 callback, which is not ideal. In this case, the event can be assigned to the responsible by default (for instance a Sales Manager). If you have a pool of undealt with leads in CRM and users themselves take leads and become responsible according to an internal algorithm, the option to create a responsible by default can be skipped.
Telephony settings in CRM are usually available only to the user with administrator/manager access. For call centers displaying remaining Zadarma balance on the telephony settings page can be useful. You can obtain balance using this method GET /v1/info/balance/
3. Outgoing calls from CRM interface ▾
3.1 WebRTC widget for calls from the browser.
If your CRM is using https you can set up our widget. Note: Do not place the widget in public domains otherwise anyone will be able to make calls using your account. With every page load from the server code side you need to generate a webrtc key that can be obtained using method GET /v1/webrtc/get_key from our API (Key lifetime - 72 hours).
In your personal account on the Settings – Integrations and API page in the section "WebRTC widget integration" you need to enter your CRM domain and choose widget display and placement settings. Then use the obtained code to integrate it with your CRM. Instead of YOUR_KEY place the key generated via API; instead of YOUR_SIP input your SIP-number or full PBX extension number login that will be used to make calls.
Code sample:
<script src="https://my.zadarma.com/webphoneWebRTCWidget/v8/js/loader-phone-lib.js?v=17"></script>
<script src="https://my.zadarma.com/webphoneWebRTCWidget/v8/js/loader-phone-fn.js?v=17"></script>
<script>
if (window.addEventListener) {
window.addEventListener('load', function() {
zadarmaWidgetFn('YOUR_KEY', 'YOUR_SIP', 'square' /*square|rounded*/, 'en' /*ru, en, es, fr, de, pl, ua*/, true, "{right:'10px',bottom:'5px'}");
}, false);
} else if (window.attachEvent) {
window.attachEvent('onload', function(){
zadarmaWidgetFn('YOUR_KEY', 'YOUR_SIP', 'square' /*square|rounded*/, 'en' /*ru, en, es, fr, de, pl, ua*/, true, "{right:'10px',bottom:'5px'}");
});
}
</script>
Hidden widget:
Expanded widget:
3.2 Callback calls
In CRM interface next to each phone number add an icon/ button for call initiation to that phone number, we also recommend to have a web-phone with number dialing for calls to new numbers, not previously saved in CRM. Outgoing calls are realized using Callback principle. An IP-phone or softphone for making and receiving calls has to be set up for PBX extension numbers. The CRM user clicks on the icon next to the number or a call button on the web-phone, Callback is sent from the CRM side.
Method GET /v1/request/callback/
Parameters:
- from – three digit PBX extension number that was assigned to the user.
- to – phone number that the user wants to call.
The user receives an incoming call to their softphone, takes it and waits for the connection to the number he/she wants to reach.
Realization example:
4. Pop-up call notifications in CRM interface ▾
When the PBX extension number receives or makes a call, there has to be an appropriate notification in CRM. The notification should only appear for the users whose extension numbers participate in the call. The notification might contain the following information:
- Phone number
- Contact name/company/lead if the phone was previously saved in CRM, the name represents a link to the essence (contact/company/lead)
- If the call is from a new client – a button to create a contact/company/lead
- Name of the responsible employee, if the call is from an existent client
- Virtual number that received an incoming call (number connected to Zadarma)
An event is a trigger for the pop-up notification NOTIFY_INTERNAL (start of the incoming call to PBX extension number) or an event NOTIFY_OUT_START (start of an outgoing call from PBX)
When the call is answered and the conversation starts, CRM will receive a notification NOTIFY_ANSWER (answer to the call on the extension number or external line), which will trigger a pop-up notification, when receiving NOTIFY_ANSWER a call duration count can start in real time in the notification, as well as a notification title “Call from 442037691880” can be changed to “Conversation with 442037691880”
When a call is ended, a notification will be sent NOTIFY_END (the end of the call to PBX extension number) or NOTIFY_OUT_END (the end of an outgoing call from PBX
After receiving NOTIFY_END or NOTIFY_OUT_END the pop-up notification has to close.
Realization example:
5. Audio records and call statistics ▾
To upload audio files from Zadarma to CRM, call recording to the cloud has to be set up in the PBX extension number settings. After finishing a call, when the audio file will be available for download, the CRM will receive a notification NOTIFY_RECORD (call recording is ready for download)
The call_id_with_rec parameter has an identification using which you can obtain the call recording, for that we use method GET /v1/pbx/record/request/. The response will include a link to the audio file, if you CRM has a storage cloud, the recording can be automatically uploaded there. If there is no storage, a play button can be added for audio playing from the link. Play button can be placed next to the information about the call, such as lead/contact/deal and in general call statistics.
For creating general call statistics in CRM, the information received from NOTIFY_END and NOTIFY_OUT_END has to be used.
6. Automatic contact/lead/deal creation during a call from a new client ▾
Automatic essence or event creation in CRM during incoming calls from unknown numbers or outgoing calls to unknown numbers. When receiving a call or initiating one, the phone number is verified against the CRM database and, if not found, you can create a new contact/lead/deal/request and assign the essence to the user making the call. We recommend creating separate options for automatic event creation for incoming and outgoing calls. For outgoing calls the essence can be created when: call is initiated (notification NOTIFY_OUT_START), when call is answered (notification NOTIFY_ANSWER), when call is finished (notificationNOTIFY_OUT_END). The phone number that was dialed is identified in parameter destination
For incoming calls the essence can be created when call is received by the CRM user’s PBX extension number (notification NOTIFY_INTERNAL, caller’s number is identified in caller_id parameter) so that during the call the user can access the client’s card, edit it, add notes etc. After the call ends, a notification is NOTIFY_END, in which in internal parameter will show the PBX extension number that received the call, verifying it with the list of CRM users to find the responsible one. Or the essence can be created after the call is finished after receiving NOTIFY_END. Certain CRM systems do not use automatic essence creation, giving agents an opportunity to decide whether the call was a target call or not and create a lead/contact/task by hand.
7. Automatic incoming call routing to the responsible employee ▾
During an incoming call from an existent client (whose number is already saved in CRM) the call is automatically routed to the user responsible for the client, the caller does not have to listen to the voice greeting and then ask to be connected to the agent they have just talked to, their call will be automatically routed to the responsible agent – the CRM user. It can be accomplished via the notification NOTIFY_START
Caller’s number is shown in caller_id parameter, if it has been previously saved in CRM, for example as a client’s contact number and that client has a responsible agent, the incoming call can be directed to the responsible agent. You can also set the duration of the call to the responsible agent, for instance, 15 seconds, if the responsible agent is out or unavailable to answer the call, in 15 seconds client’s call will be returned to the voice menu and the call will follow the PBX scenario. This can be realized via a response to POST request NOTIFY_START
{
"redirect": “101”,
"return_timeout": “15”
}
where,
- redirect – PBX extension number (three digits number).
- return_timeout – Value in seconds >= 3 – the duration of call to the extension number before the call is returned to the menu, recommended value 15 or 20.
8. Client name display in IP-phone/softphone ▾
This option allows to send the client’s name from CRM to an IP-phone or softphone of the user who accepts an incoming call. This can be realizes via a notification NOTIFY_START and in response to it, the caller’s number is shown in the notification in caller_id parameter, if the number is already saved in CRM and connected to a client/contact/lead, in response to NOTIFY_START the client’s name can be shown:
{
"caller_name": "IBM"
}
where,
- caller_name – client/company name in CRM.
9. Missed calls reminders ▾
During an incoming call from a client when receiving notification NOTIFY_END from caller_id parameter you can receive caller’s number and find the client/contact/lead with this number and the responsible agent. If the call was not answered, the call status is Not Answered in parameter disposition, the responsible agent can create a task/reminder/notification that there was a missed call from a client.
10. Blacklist in CRM ▾
You can create a list of numbers which calls will be declined, you can add numbers on the telephony settings page or add a button for each user. This can also be realized on the basis of notification NOTIFY_START and a response to it, if the caller’s number in caller_id parameter is in the CRM blacklist in response to NOTIFY_START send:
{
"redirect": "blacklist"
}
11. Adding the integration to Zadarma personal account▾
After successful completion of the previous steps and one-user testing, you can submit a request to have your integration added to Zadarma marketplace (if the monthly traffic of your system’s website exceed 30,000 users) This will allow any Zadarma user with an active account and set PBX to use the integration. It will also allow the end-user to quickly and conveniently save all the necessary settings. Requests have to be directed to the email integration@zadarma.com with a subject "Request to add integration with [Name of your СRM] system to Zadarma marketplace". The request has to contain the following additional information:
URL-address in your CRM for integration enabling
The information about the Zadarma user, who tries to integrate the telephony and your CRM, will be sent to this address. In a chosen format (GET, POST) you will receive a unique user identification in a form of md5 hash line. In response, you have to send back a randomly generated key, which will be assigned to this user. In the future for each request to your CRM system, the user identification and hash sent by you will be used as user’s verification data with a title:
Authorization: Bearer [userId . hash]
User identification will also be sent in each call notification in the field zdUserId. Examples of possible answers are necessary.
URL-address in your CRM for integration disabling
A request to disable the integration will be sent to this address. The standard Bearer authorization is used.
URL-address in your CRM for call notifications
Call notifications are sent to all integrated users. The user can be identified via the field zdUserId. Notification format can be found on the API description page. The standard Bearer authorization is used.
URL-address to your CRM which can be addressed to receive the client’s name by the phone number
Necessary for the feature “Client name display on softphone”. An example of a request and possible answers is necessary. The standard Bearer authorization is used.
(Optional) URL-address in your CRM which can be addressed to receive a list of managers
Necessary for the feature “Connecting managers to PBX extension numbers”. This will allow the user to compare the list of CRM managers and Zadarma PBX extension numbers. In case there is a need to sync this information with your CRM, you have to also specify the URL-address to send it to in JSON-format. An example of a request and possible answers is necessary. The standard Bearer authorization is used.
Displayed name of the author of the integration (can be your company name and a link to the main page)
Integration logo in PNG format on a transparent background, size 500 x 150px
We recommend to make features from items 6-10 optional so that the end-user can enable/disable needed features on the page “Telephony settings” in CRM