Integration of your CRM and telephony

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:

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:

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.

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.

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.

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.

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.

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" 
}

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