Articles in this section
Phone Calls API Usage
Table of Contents
Introduction
With Phone Calls API, you can integrate your phone system with Vtiger to achieve these features
- Click-to-call,
- Incoming call popup,
- Call logging in CRM &
- Recording link
Vtiger CRM Cloud editions offer APIs to track calls made from your telephony system. Using these APIs you can easily trigger popups in the CRM for incoming calls, update recording url, call status and call notes in Phone Calls module record.
Configuration
To configure Phone Calls module, follow these steps:
- Hover on Menu and click Phone Calls module.
- Click on customize button and select Phone Configuration.
- Click on Add Gateway and select “Generic” gateway from the dropdown.
After you save this gateway it will give you a Vtiger Secret Key, which should be passed in the header with the key
“X-VTIGER-SECRET” for every API.
NOTE! : Make sure your crm user’s Office Phone is configured for this, without this it will not show the call popup inside the crm.
For Outgoing Calls
After you select the Generic Gateway type, configure Outgoing Call details. Here, 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 as FORM. Next, you can authenticate your service by providing username and password or continue without any authentication. Lastly, add the parameters that you need to pass to the end point.
Consider an example of Duocom as a Telephony service provider. For more information, click here.
Enhancement:
- You now have URL-based authorization for outgoing calls in the Generic Gateway configuration. Generic Gateway is a service provider similar to Twilio, Plivo, and Exotel.
- The URL will return a response that is 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.
For Incoming Calls
For Incoming calls, phone system should notify Vtiger using the APIs documented below.
Note : All of them use the below end point. https://URL_INSTANCE_URL/modules/PhoneCalls/callbacks/Generic.php
Call Events
Here are the API details.
1. Call Initiated Event
Trigger this callback to log the call and show incoming call notification to all users in Vtiger when a call is started/initiated. The call log is created with call status set to ‘ringing’.
Example:
should be replaced with your instance URL - Ex: acme.od2.vtiger.com
Parameters
| Name | Type | Description |
|---|---|---|
| from (required) | string | this is the customer’s phone number |
| to | string | this is CRM User’s number which should be set to 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 then we will search if “from” number is associated to any user and decide on the direction. |
2. Call Connected Event
This callback can be sent when a call is established between the caller and the callee. After the call is picked up you will know which agent actually picked up the call. It will change Phone Calls record status to “in-progress“.
We will use “to” parameter to identify the actual 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 CRM User’s number which should be set to 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 call recording is ready. You need to pass call_id and recording_url to capture the recordings.
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 whea n call is transferred. 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 |
5. Call Hangup Event
Trigger this callback after a call is completed to remove call notification and update call log with call hangup details. Phone Calls 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 hangup reason like not answered, busy or call completed etc this will set the Call Status accordingly in the below table (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
Following API will open the Contact/Lead/Organization record that has 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 matching record in Vtiger and User is logged in, then Vtiger user is redirected to the matching Contact record.
- If there is no matching record and User is logged in, then Vtiger user is prompted to create the new Contact record in Vtiger.