Home  >   Articles   >  Phone Calls API Usage

Phone Calls API Usage

B
Bindu Rekha Babu
13 Jun, 2023 - Updated 9 months ago
Table of Contents

Introduction

With Phone Calls API, you can integrate your phone system with Vtiger to achieve these features

  1. Click-to-call,
  2. Incoming call popup,
  3. Call logging in CRM &
  4. 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, and update the recording url, call status and call notes in Phone Calls module record.

Configuration

To configure Phone Calls module, follow these steps:

  1. Hover on Menu and click Phone Calls module.
  2. Click on customize button and select Phone Configuration.
  3. 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.

image not found

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.

Workflow 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, 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:
image not found

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:
image not found

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:
image not found

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:
image not found

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:
image not found

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:
image not found

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.
Was this article helpful?
1  out of  1  found this helpful.
Comments 0
Be the first to comment
© Copyright 2023 Vtiger. All rights reserved.