Home  >   Articles   >  Phone Calls API Usage

Phone Calls API Usage

B
Bindu Rekha Babu
23 May, 2024 - Updated 1 month ago
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: 

  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

image not found

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

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

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

  1. 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:

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

  1. Call Transferred Event

Trigger this callback when the call is transferred. Note: 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
 
  1. 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:
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 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:
image not found

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.

 
Was this article helpful?
1  out of  1  found this helpful.
Comments 0
Be the first to comment
© Copyright 2023 Vtiger. All rights reserved.