Articles in this section
Phone Calls API Usage
Table of Contents
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
Configuring the Phone Calls Module
Follow these steps to configure the Phone Calls module:
- Log in to the CRM.
- Go to the main Menu.
- Go to Essentials.
- Go to Conversations.
- Click the Phone Calls module.
- Click Settings (wheel icon).
- Select Provider Configuration.
- Click Add Gateway.
- Select Generic gateway from the dropdown.
- 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:
- Add the telephony services’ REST API URL to track the calls.
- Select either POST or GET to send the request. By default, the content type is set to FORM.
- Authenticate your service by providing a username and password
- Or continue without any authentication.
- 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:
- 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. |
- 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 |
- 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 |
- 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 |
- 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.