Welcome to the Freshdesk CTI documentation!
CTI is the framework that enables you to build and integrate your telephone system with Freshdesk.
This integration provides softphone framework using which you can build your softphone within Freshdesk. We also provide set of basic APIs that will help you to access customer’s ticket history, take call notes, create freshdesk ticket from the customer calls thereby, maintaining context for the entire conversation in Freshdesk.
Feature Availability:
Feature | Freshdesk plans |
Screenpop API | Blossom, Garden, Estate, Forest |
Call Details API | |
Softphone Iframe |
Note:
1. Prior to installing the app, you need to check if the CTI feature is enabled for your account, if not contact us at
support@freshdesk.com to get the feature enabled.
2. This integration does not provide with any kind of softphone functionality. However, it provides an iframe to help you
build your softphone in Freshdesk.
Freshdesk CTI
There are two APIs you can use to integrate your telephony system with Freshdesk. They are:
Screenpop API - Once a custom softphone is integrated within freshdesk, this API will be used to:
- Display the requester information in a pop window
- Link to an existing ticket or link to a new ticket from a customer call.
- View the requester’s recent tickets(ticket history)
- Take call notes for later reference.
- Call Details API- You can use this API to retrieve the following information:
- ticket_id - If a new ticket was created from a customer call.
- note_id and ticket_id - If a customer call was linked to an existing ticket.
- You can use this API to fetch information for the calls that were either linked to a new ticket or an existing ticket.
Note: Currently, freshdesk supports only the above mentioned API.
Screenpop API
The API to call is:
POST | /api/v2/integrations/cti/pop |
Parameters:
Attribute | Type | Description |
requester_id⁺ | number | Freshdesk user_id of the requester |
requester_phone⁺ | text | Phone number that the requester is calling from |
requester_email⁺ | text | Freshdesk email of the requester |
responder_id^ | number | User_id of the agent receiving the call |
responder_phone^ | text | Agent phone number if the number to agent mapping is maintained in Freshdesk |
responder_email^ | text | Freshdesk email of the responder |
call_reference_id* | text | Telephony UID for a given call |
ticket_id | number | Freshdesk ticket ID if this call is with reference to an existing ticket |
new_ticket | boolean | If set to true, then a new ticket will be popped up. This setting will override the display of an existing ticket associated with the same call_reference_id (call forwarding scenario) |
call_url | text | The URL of the call recording |
call_info | hash | A combination of key value pairs that will have the call parameters that can be added to the call recording to add additional context to the call |
^Any of the three responder attributes is mandatory
*Denotes Mandatory parameter
Sample POST Request:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic VHcyUlBPUk9JbEVUd2lIRUc3UTc6WA==" -H "Cache-Control: no-cache" -H
"Postman-Token: 23058f62-71be-fb16-06be-1eb884eb676d" -d '{
{
"requester_id": "5014967434",
"responder_email": "saul@freshdesk.com",
"new_ticket": "true",
"call_info": {
"Organisation": "XYZ",
"Reason": "Priority issue raised.."
}
}Sample Response:
{
"id": "5000001876"
}Parameter Explanation:
The following section explains in detail about each parameter of the API, their data types and how they are handled
Requester ID or Requester Phone
Requester_id is the user ID of the Freshdesk requester and requester_phone is their phone number. If requester_id is passed, requester_phone will be ignored. However, requester_phone may also be passed when the search for the Requester ID returns more than one number. If requester_id is invalid, then an error will be returned.
Requester_email is the email of the Freshdesk requester. Here's a change!
Agent User ID (CTI Managed Agent Mapping)
In this case, the responder_id parameter will be passed based on the mapping of the call center number with the agent’s user ID (responder_id). If an agent match is not found then an exception will be returned.
Agent Phone (Freshdesk Managed Agent Mapping)
In this case, responder_phone parameter will be passed. If an agent match is not found then an exception will be returned.
Agent Email
Responder_email is the email of the Freshdesk requester.
Call Reference ID
If the call_reference_id is passed, then it will be added to the ticket that this call is associated with a time sheet entry. The call_reference_ID exists only when a call_id is associated with a new ticket. If the call_id was associated with a note inside a given ticket, then the call_id will have a note_id associated with it. The timesheet entry starts when the API is first called and the timer ends when the call is associated with the ticket.
Ticket ID
If the end user enters ticket ID or if Ticket ID is passed during a call, then the CTI widget will contain a link to that ticket.
New Ticket
If the agent selects the New Ticket option, the Freshdesk CTI will create a new ticket and display it in the Screenpop widget. The widget will also show the relevant information regarding the customer to the agent.
The agent will have the option of either adding a note to the ticket during the call or dismissing the pop-up.
Call URL
When you pass the Call URL to the Freshdesk CTI app, the audio file will be embedded in the ticket/note that is created. If there isn’t a ticket associated with the call already, then a new one is created and the audio file of the call is embedded in a private note that is linked to the new ticket. If a ticket already exists, then a private note is created and the audio file is embedded in it.
Call Info
Any other information that needs to be displayed in the ticket can be sent as key-value pair (JSON) and this will be appended in the note that gets created along with the ticket.
Call Details API
The API to call is:
GET | api/v2/integrations/cti/details |
Parameters:
Attribute | Type | Description |
call_reference_id* | text | Call Reference ID passed during the screenpop |
Sample GET Request:
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic cHJpeW9AbWFpbGluYXRvci5jb206dGVzdA==" -H "Cache-Control: no-cache" -H "Postman-Token: 23058f62-71be-fb16-06be-1eb884eb676d" 'https://saul.freshdesk.com/api/v2/integrations/cti/details?call_reference_id=226356'Sample Response:
[ {
"requester_id": 5014967434,
"responder_idl": 7898974314,
"ticket_id": 80,
"note_id": 511298683,
} ]Request Handling
This section describes how the APIs and incoming requests are handled by the Freshdesk CTI app based on the calls and the parameters available.
The request handling workflow is independent of whether the CTI manages the agent mapping or the helpdesk manages the agent mapping but once the user_id has been mapped, all incoming requests will be handled primarily in one of the following scenarios:
- Agent is offline on the Freshdesk browser
- Agent is online on the Freshdesk browser
If the agent is offline:
If the agent is offline in Freshdesk, then based on the following conditions, requests will be handled:
Requester ID was provided
A new ticket will be created along with the Call_url and the call_reference_id based on configured options.
Requester Phone was provided
If the requester_phone parameter is passed from the telephony system to the CTI app, then, the depending on the match, the following things will happen:
The requester phone number passed from the telephony system is matched with “Phone” number in Freshdesk. If a unique match is found, then the widget will be populated with details from the relevant Freshdesk account.
If no account is found with a matching “Phone” number in Freshdesk, then a match for “Mobile” numbers is done. Based on the account found, the CTI widget is populated.
If more than one user in Freshdesk is matched with the same phone or mobile number, then the first user matched will be displayed in the widget along with their details.
If the Requester Phone matches no users in Freshdesk, then a new user will be created.
The new user created will have the phone number set as their Name in Freshdesk. Agents can change this at any point.
If the Agent is online:
If the agent is online in Freshdesk, then based on the following conditions, requests will be handled.
'New Ticket' option is selected
If the Admin has selected the “New Ticket” option in the configuration screen, then during the call, a new ticket will be created when the call comes in and the ticket will automatically be associated with the call. The agent answering the call will not have the option of creating another one. Since the Requester ID has been passed as well, the CTI widget will show relevant information but agents will not have the option to add comments, convert to a ticket or linked with a ticket. The call_url parameter will automatically be populated as a private note when the ticket page is loaded.
Ticket ID is passed
If the ticket ID is passed, then the relevant ticket is displayed in the Freshdesk CTI widget. In addition, the CTI widget appears with the customer profile details such as name (hyperlinked to Freshdesk profile), location, and three most recent tickets (if any).
If no Ticket ID is passed, then the Freshdesk CTI widget is shown with just the Requester Details. The agent will also have access to a digital notepad within the widget to take notes on the call. Once the call has ended, the agent can either:
- Link the call to an existing ticket or associate it with a new one
- Forward it for further action to another agent.
The notes taken will be automatically linked as a private note along with the ticket linked to the call.
Close the Call
After the call, the support agent may link the call to a new ticket or associate the call to the current ticket displayed on the screen. At the end of the call, a link to the call recording will be added as an update to the ticket.
Call Forwarded to another agent
A call can be transferred to another agent after performing one of the following actions:
- Creating a new ticket
- Updating an existing ticket
- Forward without performing any Freshdesk actions
If the call is transferred to an agent, after performing a create ticket or update ticket action, then the call reference ID will already be associated with the ticket.
Softphone IFrame
The softphone iframe can be used for rendering custom softphones and also enable custom features. Currently Freshdesk supports you to open a particular ticket within Freshdesk using the ticket ID from the iframe window, similarly, you can also view requester information using the corresponding contact ID.
Configure Softphone IFrame
1. Log into Freshdesk, go to Admin-> Apps.2. Click the CTI settings icon.
3. Turn ON the enable softphone Iframe toggle.
4. Enter the Iframe URL, you can append the agent_id in order to receive this parameter in your request. Follow the format as shown in the example below:
Note: Currently agent_id is the only supported parameter.
6. In the Helpdesk Numbers section, click Add Number, enter the helpdesk number(s) and click Save.
7. Once added, the number(s) will appear in the agent's console through which each agent can select their helpdesk number from the Agent phone details popup as shown below: 
Note: Admins will not be able to freeze the Agent-Helpdesk Number mapping.
The following table lists the available APIs:
| To: | Use API: |
| Open the iframe | window.parent.postMessage({action: "show_softphone"}, '*'); |
| Open ticket inside freshdesk | window.parent.postMessage({action: "open_ticket", value:<TICKET_ID>}, '*'); |
| Open contact inside freshdesk | window.parent.postMessage({action: "open_contact", value:<CONTACT_ID>}, '*'); |
Configure Click to Dial:
The Click to Dial setting enables you to send the parameters (requester_number, agent_number, agent_id, ticket_id, and requester_id) when the corresponding field is clicked in the UI.
1. Log into Freshdesk, go to Admin->App.
2. Click the CTI settings icon.
3. Turn ON the Configure Click to Dial toggle.
4. Select the Request Type.
5. Enter the callback URL as shown in the example below:
Where requester_number will be sent with the request.
Handling Corner Cases
If the Browser Hangs
Refreshing the page will refresh the CTI widget as well and the cause for the hang should be solved. If this doesn’t work and if the user’s helpdesk is still not responsive, please contact us at support@freshdesk.com
Server Side Crash
In case of a server-side crash, then the agent will appear offline to any and all users. Any CTI APIs called will automatically trigger a ticket so that cause for server crash can be resolved.
API invoked before Call Dispose
If the agent answers a new call while the widget from the previous call is still open, the following things will happen:
- The previous call’s widget will close
- A new ticket will be created automatically and any/all details from the previous call will be associated with it. The agent who attended the call will be automatically assigned as the agent dealing with that ticket.
- A CTI widget will pop-up with the relevant details of the latest caller.