Introduction:

WelcometotheFreshdeskCTIdocumentation!Ifyouwishtointegrateyourtelephonesystem
withFreshdesk,thisdocumentationcontainsalltheAPIsyoullneedirrespectiveofwhether
youhaveaCloudbasedoranOnPremisePBXsystem.Onceintegrated,asupportagent
usingthesystemwillbeableattendcalls,accesscustomerhistoryanddetailseasily,provide
supportandmaintaincontextfortheentireconversationwithinFreshdeskthroughoutthecall.

WiththeFreshdeskCTIAPIs,agentswillbeableto:

1. AttendandmakecallsdirectlyfromwithinFreshdesk.Thesimpler,unifiedinterface
ensuresthatirrespectiveofwhichtelephonyprovideryouintegratewith,agentswont
havetorelearnanyprocesses.
2. Getcontextregardingthecustomersproblemsassoonasthecallcomesin.View
requestertickethistoryaswellasotherdetails.

FreshdeskCTI
TherearetwoAPIsyoucanusetointegrateyourtelephonysystemwithFreshdesk.Theyare:
1. ScreenpopAPIwhichhandlestheUIpartoftheintegration.Whentheagentwantsto
receiveacallormakeone,orconvertacalltoaticketandforotherfunctions,thisAPI
willbeuseful

2. CallDetailsAPIWhenanagentreceivesacall,thisAPIisusedtoautomaticallymatch
theincomingcallnumberwithexistingcontactsinFreshdesk.Anydetailsobtained
throughamatchwillbedisplayedtotheagentviatheScreenpopAPItogivehimbetter
contextwhiletalkingtothecustomer.

ScreenpopAPI

TheAPItocallis:
/api/v2/integrations/cti/pop

Parameters:

Attribute

Type

Description

requester_id

number

Freshdeskuser_idofthe
requester

requester_phone

text

Phonenumberthatthe
requesteriscallingfrom

responder_id

number

User_idoftheagent
receivingthecall

responder_phone

text

Agentphonenumberifthe
numbertoagentmappingis
maintainedinFreshdesk

call_reference_id

text

TelephonyUIDforagiven
call

ticket_id

number

FreshdeskticketIDifthiscall
iswithreferencetoan
existingticket

new_ticket

boolean

Ifsettotrue,thenanew
ticketwillbepoppedup.This
settingwilloverridethe
displayofanexistingticket
associatedwiththesame
call_reference_id(call
forwardingscenario)

call_url

text

TheURLofthecallrecording

call_info

hash

Acombinationofkeyvalue
pairsthatwillhavethecall
parametersthatcanbe
addedwiththecallrecording
toaddadditionalcontextto
thecall

ParameterExplanation:
ThefollowingsectionexplainsindetailabouteachparameteroftheAPI,theirdatatypesand
howtheyarehandled

RequesterIDorRequesterPhone
requester_idistheuserIDoftheFreshdeskrequesterandrequester_phoneistheirphone
number.Ifrequester_idispassed,requester_phonewillbeignored.However,requester_phone
mayalsobepassedwhensearchfortheRequesterIDreturnsmorethanonenumber.

Ifrequester_idisinvalid,thenanerrorwillbereturned.

AgentUserID(CTIManagedAgentMapping)
Inthiscasetheresponder_idparameterwillbepassedbasedonthemappingofthecallcenter
numberwiththeagentsuserID(responder_id)

AgentPhone(FreshdeskManagedAgentMapping)
Inthiscase,responder_phoneparameterwillbepassed.

Inbothcases,FreshdeskmanagedmappingorCTImanagedmapping,ifanagentmatchisnot
foundthenanexceptionwillbereturned.


CallReferenceID
Ifthecall_reference_idispassed,thenitwillbeaddedtotheticketthatthiscallisassociated
withatimesheetentry.Thecall_reference_IDisexistsonlywhenacall_idisassociatedtoa
newticket.Ifthecall_idwasassociatedtoanoteinsideagiventicket,thenthecall_idwillhave
anote_idassociatedwithit.

ThetimesheetentrystartswhentheAPIisfirstcalledandthethetimerendswhenthecallis
associatedwiththeticket.

TicketID
IfenduserentersticketIDorifTicketIDispassedduringcall,thentheCTIwidgetwillcontaina
linktothatticket.

NewTicket
IftheagentselectstheNewTicketoption,theFreshdeskCTIwillcreateanewticketand
displayitintheScreenpopwidget.Thewidgetwillalsoshowtherelevantinformationregarding
thecustomertotheagent.

Theagentwillhavetheoptionofeitheraddinganotetotheticketduringthecallordismissing
thepopup.

CallURL
WhenyoupasstheCallURLtotheFreshdeskCTIapp,theaudiofilewillbeembeddedinthe
ticket/notethatiscreated.Ifthereisntaticketassociatedwiththecallalready,thenanewone
iscreatedandtheaudiofileofthecallisembeddedinaprivatenotethatislinkedtothenew
ticket.Ifaticketalreadyexists,thenaprivatenoteiscreatedandtheaudiofileisembeddedin
it.

CallInfo
Anyotherinformationthatneedstobedisplayedintheticketcanbesentaskeyvaluepair
(JSON)andthiswillbeappendedinthenotethatgetscreatedalongwiththeticket.

CallDetailsAPI
TheAPIis

api/v2/integrations/cti/details

Parameters:

Attribute

Type

Description

call_reference_id

text

CallReferenceIDpassed
duringthescreenpop

CallReferenceID
TheCallReferenceIDispassedduringscreenpop.Formoredetails,clickhere

RequestHandling
ThissectiondescribeshowtheAPIsandincomingrequestsarehandledbytheFreshdeskCTI
appbasedonthecallsandtheparametersavailable.

TherequesthandlingworkflowisindependentofwhethertheCTImanagestheagentmapping
orthehelpdeskmanagestheagentmappingbutoncetheUser_IDhasbeenmapped,all
incomingrequestswillbehandledprimarilyinoneoftwoways:

1. TheAgentisofflineontheFreshdeskbrowser
2. TheAgentisonlineontheFreshdeskbrowser

Iftheagentisoffline:

IftheagentisofflineinFreshdesk,thenbasedonthefollowingconditions,requestswillbe
handled

RequesterIDwasprovided
AnewticketwillbecreatedalongwiththeCall_urlandthecall_reference_idbasedon
configuredoptions.

RequesterPhonewasprovided
Iftherequester_phoneparameterispassedfromthetelephonysystemtotheCTIapp,then,the
dependingonthematch,thefollowingthingswillhappen:
Therequesterphonenumberpassedfromthetelephonysystemismatchedwith
PhonenumberinFreshdesk.Ifauniquematchisfound,thenthewidgetwillbe
populatedwithdetailsfromtherelevantFreshdeskaccount.
IfnoaccountisfoundwithamatchingPhonenumberinFreshdesk,thenamatchfor
Mobilenumbersisdone.Basedontheaccountfound,theCTIwidgetispopulated.
IfmorethanoneuserinFreshdeskismatchedwiththesamephoneormobilenumber,
thenthefirstusermatchedwillbedisplayedinthewidgetalongwiththeirdetails.
IftheRequesterPhonematchesnousersinFreshdesk,thenanewuserwillbecreated.
ThenewusercreatedwillhavethephonenumbersetastheirNameinFreshdesk.
Agentscanchangethisatanypoint.

IfAgentisonline
IftheagentisonlineinFreshdesk,thenbasedonthefollowingconditions,requestswillbe
handled.

NewTicketoptionisselected
IftheAdminhasselectedtheNewTicketoptionintheconfigurationscreen,thenduringthe
call,anewticketwillbecreatedwhenthecallcomesinandtheticketwillautomaticallybe
associatedwiththecall.Theagentansweringthecallwillnothavetheoptionofcreating
anotherone.SincetheRequesterIDhasbeenpassedaswell,theCTIwidgetwillshow
relevantinformationbutagentswillnothavetheoptiontoaddcomments,converttoaticketor
associatewithaticket.Thecall_urlparameterwillautomaticallybepopulatedasaprivatenote
whentheticketpageisloaded.

TicketIDispassed
IftheticketIDispassed,thentherelevantticketisdisplayedintheFreshdeskCTIwidget.In
additiontheCTIwidgetappearswiththecustomerprofiledetailssuchasname(hyperlinkedto
Freshdeskprofile),location,andthreemostrecenttickets(ifany).

IfnoTicketIDispassed,thentheFreshdeskCTIwidgetisshownwithjusttheRequester
Details.Theagentwillalsohaveaccesstoadigitalnotepadwithinthewidgettotakenoteson
thecall.Oncethecallhasended,theagentcaneither:

1. Linkthecalltoanexistingticketorassociateitwithanewone
2. Forwarditforfurtheractiontoanotheragent.

Thenotestakenwillbeautomaticallyassociatedasaprivatenotealongwiththeticketlinkedto
thecall.

ClosetheCall
Afterthecall,thesupportagentmaylinkthecalltoanewticketorassociatethecalltothe
currentticketdisplayedonthescreen.Attheendofthecall,alinktothecallrecordingwillbe
addedasanupdatetotheticket.

CallForwardedtoanotheragent
Acallcanbetransferredtoanotheragentafterperformingoneofthefollowingactions,

Creatinganewticket
Updatinganexistingticket
ForwardwithoutperforminganyFreshdeskactions

If the call is transferred to an agent,afterperformingacreate ticketorupdateticketaction,then

thecallreferenceIDwillalreadybeassociatedwiththeticket.

HandlingCornerCases

IftheBrowserHangs
RefreshingthepagewillrefreshtheCTIwidgetaswellandthecauseforthehangshouldbe
solved.Ifthisdoesntworkandiftheusershelpdeskisstillnotresponsive,pleasecontactusat
support@freshdesk.com

ServerSideCrash
Incaseofaserversidecrash,thentheagentwillappearofflinetoanyandallusers.AnyCTI
APIscalledwillautomaticallytriggeraticketsothatcauseforservercrashcanberesolved.

APIinvokedbeforeCallDispose
Iftheagentanswersanewcallwhilethewidgetfromthepreviouscallisstillopen,thefollowing
thingswillhappen:
1. Thepreviouscallswidgetwillclose
2. Anewticketwillbecreatedautomaticallyandany/alldetailsfromthepreviouscallwillbe
associatedwithit.Theagentwhoattendedthecallwillbeautomaticallyassignedasthe
agentdealingwiththatticket.
3. ACTIwidgetwillpopupwiththerelevantdetailsofthelatestcaller.

HowtousetheCTIAPI

Adminswillhavethefollowingcontrolsavailableforconfiguration.Oncetheintegrationhas
beeninstalled,