Actions - Your Personal Assistant Adding Multiple Signatories with Esign Documents Contact Management Esign Documents Module Creating Approvals in Vtiger CRM Cut costs with Vtiger Managing Organizations Managing your Documents Managing your Events Managing your Tasks One View in Contacts One View in Organizations SMS Messages DMARC Records in Vtiger CRM Vtiger Inbox Reports and Analytics in Vtiger Lead Management Configuring SMS Gateways in Vtiger Live Chats in Vtiger CRM Creating your Dashboard Targets Add-on MMS Messages via Twilio Using the Calendar Page

Introduction

Vtiger CRM offers APIs to track calls made from your telephony system. Using these APIs, you can integrate your telephone service provider with Vtiger CRM and use the following features:

• Click-to-call
• Incoming call popup
• Call logging in CRM
• Recording link

With these features, you can:

• Easily trigger popups in the CRM for incoming calls
• Update the recording URL, call status, and call notes for a phone call record in the Phone Calls module

 

Benefits of Phone Calls API

Here are some benefits of phone calls API:

• Manage all phone calls within the CRM system.
• Initiate calls directly from the CRM with a simple click.
• Provide better customer experience with personalized interactions.
• Gain insights into call performance.
• Automatic route calls to the appropriate agents based on skills, availability, and customer preferences.

Configuring the Phone Calls Module

Follow these steps to configure the Phone Calls module: 

1. Log in to the CRM.
2. Go to the main Menu.
3. Go to Essentials.
4. Go to Conversations.
5. Click the Phone Calls module.
6. Click Settings (wheel icon).
7. Select Provider Configuration.
8. Click Add Gateway.
9. Select Generic gateway from the dropdown.
10. Click Save.

After you save this gateway, the screen will display the Vtiger Secret Key, which should be passed in the header with the key X-VTIGER-SECRET for every API.
Note: Ensure your CRM user’s Office Phone is configured for this. Without the Phone Office number, the call pop-up will not appear inside the CRM.

Configuring Outgoing Calls for a Gateway

​​

After you select the Generic Gateway type, follow these steps to configure outgoing call details:

1. Add the telephony services’ REST API URL to track the calls.
2. Select either POST or GET to send the request. By default, the content type is set to FORM.
3. Authenticate your service by providing a username and password
   1. Or continue without any authentication.
4. Add the parameters that you need to pass to the endpoint.
    

​​​​URL-based authorization for outgoing calls

You can provide URL-based authorization for outgoing calls in the Generic Gateway configuration. 

• The URL will return a response used when sending an outgoing call request.
• For example, the token URL will return the access_token in response. This access_token can be used in the request header or parameter.

Setting up Workflows from Generic Phone API

• Using the Generic Phone API, you can now set up a workflow to automatically send an email or a WhatsApp message to a customer when an incoming call is missed. 
• The Generic Phone API triggers a workflow for every phone call status update or any other update for all phone call gateways.

For Incoming Calls

For Incoming calls, the phone system should notify Vtiger using the APIs documented below.
Note: All of them use the below endpoints. 

Call Events

Listed below are API details for Call Events:

1. Call Initiated Event​​​​​​

Trigger this callback to log the call and show incoming call notifications to all users in Vtiger when a call is started/initiated. The call log is created with the call status set to ringing.

Example:
​

The above should be replaced with your instance URL - For example, acme.od2.vtiger.com.

Parameters

Name	Type	Description
from (required)	string	this is the customer’s phone number
to	string	this is the CRM User’s number, which should be set to the Office Phone field in the Users Preference page.
event (required)	string	name of the event (call_initiated)
call_id (required)	mixed	unique call identifier
direction	string	This is used to identify the direction of the call (inbound/outbound). This is an optional parameter. If not provided, Vtiger will search if the from number is associated with any user and decide the direction.

2. Call Connected Event

This callback can be sent when a call is established between the caller and the receiver. After the call is picked up, you will know which agent actually picked up the call. It will also change the Phone Call record status to in progress.
We will use the to parameter to identify the user who has picked up the call.

Example:
​

Parameters

Name	Type	Description
from	string	This is the customer’s phone number
to (required)	string	This is the CRM user's number, which should be set to the Office Phone field in the Users Preference page.
event (required)	string	name of the event (call_connected)
call_id (required)	mixed	unique call identifier

3. Call Recording Event

Trigger this callback when the call recording is ready. To capture the recordings, you need to pass call_id and recording_url.
Example:

​

Parameters

Name	Type	Description
event (required)	string	name of the event (call_recording)
call_id (required)	mixed	unique call identifier
recordingurl (required)	string	recording url

4. Call Transferred Event

Trigger this callback when the call is transferred. Note: call_id and transferred_number parameters are mandatory.

Example:
​

Parameters

Name	Type	Description
event (required)	string	name of the event (call_transfer)
call_id (required)	mixed	unique call identifier
transferred_number (required)	string	transfer agent number

 

6. Call Hangup Event

Trigger this callback after a call is completed to remove the call notification and update the call log with call hangup details. Phone Call record status is changed to complete/busy/hangup depending on the hang_reason given.

Example:
​

Parameters

Name	Type	Description
event (required)	string	name of the event (call_hangup)
call_id (required)	mixed	unique call identifier
hangup_reason	string	You can pass the hang-up reason like unanswered, busy, or call completed, etc. This will set the Call Status in the table below (default = completed).
billrate	string	bill rate
billduration	string	billing duration in seconds
recordingurl	string	recording URL
notes	string	optional call notes

Hangup reason and its mapping to call status.

hangup_reason	call status
no_answer	hangup
busy	busy
completed	completed
any_other_state	any_other_state

Search by Number API

The following API will open the Contact/Lead/Organization record with the matching number. This API can be used by 3rd part applications to open contact records easily using a phone number.

Example:
​

Results

• If there is a matching record in Vtiger and the user is logged in, the Vtiger user is redirected to the matching Contact record.
• If there is no matching record and the user is logged in, the Vtiger user is prompted to create a new Contact record in Vtiger.

References

• Phone Calls Module Overview
• Phone Calls Generic API