= Purpose= The Bright Pattern Contact Center ''Desktop JavaScript API Specification'' describes the Desktop JavaScript API that provides access to a number of functions of the Bright Pattern Contact Center Agent Desktop application from the web pages or iFrames loaded into this application from other domains. For general information about the Bright Pattern Contact Center Agent Desktop application, see the [[#topic_agent-guide/purpose|''Agent Guide'']]. For information about loading web pages into Agent Desktop from scenarios, see the ''Scenario Builder Reference Guide'', section [[#topic_scenario-builder-reference-guide/webscreenpop|Web Screen Pop]] block. = Audience= This guide is intended for the IT personnel responsible for the data infrastructure of Bright Pattern Contact Center-based contact centers. Readers of this guide are expected to have expertise in web application development as well as a solid understanding of contact center operations. = General Information= The API supports a number of desktop telephony functions, including call initiation, voice and screen recording, interaction completion, and the setting of interaction dispositions and notes. These functions are available via a global object called ''window.bpspat.api''. === Example === window.bpspat.api.dialNumber("1234567"); == Object Creation == The object is created when the script file is included in the web page loaded into the Agent Desktop application as follows: or === Example === or = Dial Number= Makes a call to the specified number. For more information, see the Bright Pattern Contact Center ''Agent Guide'', section [[#topic_agent-guide/howtomakeaninternalcall|How to Make an Internal Call]] and section [[#topic_agent-guide/howtomakeanoutboundcall|How to Make an Outbound Call]]. == Request == === Syntax === dialNumber(number); == Parameters == {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | number | String | Required | The number to be dialed | "11234567" |} = Select Service= Selects the service that will be associated with subsequent call attempts (until another service is selected using this method or via Agent Desktop). If omitted or empty, subsequent call attempts will not be associated with any service. For more information, see the Bright Pattern Contact Center ''Agent Guide'', section [[#topic_agent-guide/howtomakeaninternalcall|How to Make an Internal Call]] and section [[#topic_agent-guide/howtomakeanoutboundcall|How to Make an Outbound Call]]. == Request == === Syntax === selectService(name); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | name | String | Optional | The name of the selected service | "Voice Service" |} = setRescheduleWindow= Allows you to reschedule outbound dialing retry time to be within a specific timeframe with the option to specify a time zone. The reschedule window will only affect outbound campaigns when a non-final disposition is selected. The data is retained in Agent Desktop until changed or the interaction is completed. == Request == === Syntax === setRescheduleWindow(numberToDial, fromTime, untilTime, timezoneName); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Data Type''' | '''Required/Optional''' | '''Description''' | '''Example''' |- | numberToDial | String | Required | The phone number to dial | "11234567" |- | fromTime | String | Required | The start of the reschedule timeframe in “YYYY-MM-DD HH24:MM:SS” format | "2019-09-12 15:30:00" |- | untilTime | String | Required | The end of the reschedule timeframe in “YYYY-MM-DD HH24:MM:SS” format (must be after the starting time) | "2019-09-13 15:30:00" |- | timezoneName | String | Optional | The name of the timezone; if omitted, the timezone will be assumed to be the record’s detected timezone | “America/Los_Angeles” |- |} = Single-Step Transfer= Initiates a [[#topic_agent-guide/howtoplaceacallinaservicequeue|single-step (blind) transfer]] of the current call to the specified number. == Request == === Syntax === singleStepTransfer(number); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | number | String | Required | The number to which the call is to be transferred | 14151234567 |} = Single-Step Conference= Initiates a [[#topic_agent-guide/howtohostaconference|single-step conference]] with the current party on the call and the party at the specified number. == Request == === Syntax === singleStepConference(number); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | number | String | Required | The number for which the call is to be conferenced | "16501234567" |} = Complete Interaction= [[#topic_agent-guide/howtowrapupafter-callwork|Completes]] the current interaction. If the interaction [[#topic_contact-center-administrator-guide/propertiestab|requires a disposition]] in order to be completed, Agent Desktop will show a warning message. == Request == === Syntax === completeInteraction(); = Complete Interaction with Disposition and Notes= [[#topic_agent-guide/howtowrapupafter-callwork|Completes]] the current interaction and [[#topic_agent-guide/howtoenterdispositionsandnotes|sets its disposition and notes]] to the specified values (i.e., combines the actions of the [[#topic_desktop-javascript-api-specification/setnotes|Set Notes]], [[#topic_desktop-javascript-api-specification/setdisposition|Set Disposition]], and [[#topic_desktop-javascript-api-specification/completeinteraction|Complete Interaction]] methods). == Request == === Syntax === completeInteractionWithDisp(dispositionCode, notes); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | dispositionCode | String | Required | The [[#topic_contact-center-administrator-guide/dispositionstab|alphanumeric code]] of the desired disposition | "12345" |- | notes | String | Optional | The interaction notes | "Could not resolve. Not enough information." |} = postVariable= This function enables a variable to be pushed to a scenario as if the [[#topic_scenario-builder-reference-guide/setvariable|Set Variable]] block is included; the variable is then available in scenarios and [[#topic_contact-center-administrator-guide/workflowentries|workflows]]. When invoking the postVariable method for a variable that starts with ''ActivityHistory'', Agent Desktop memorizes the value of the variable to post it in activity history (see the ''Form Builder Reference Guide'', section [[5.3:Form-builder-reference-guide/HowtoConfigureActivityHistoryForms#Action_2:_Map_Activity_History_Values_to_Form_Fields | How to Configure Activity History Forms]] for more information on mapping activity history values). If an activity history field was marked for export in campaign results, it will be possible to export it with campaign results. The data is retained in Agent Desktop until changed or the interaction is completed. If a form is displaying that data, the form is also updated to reflect the new value. If the data changes in the form, it changes the value to be submitted. == Syntax == postVariable(name, value); == Parameters == {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Data Type''' | '''Description''' |- | name | String | The name of the desired variable |- | value | String | The resulting value of the variable |} = Set Disposition= Sets the [[#topic_agent-guide/howtoenterdispositionsandnotes|disposition]] for the current interaction to the value corresponding to the [[#topic_contact-center-administrator-guide/dispositionstab|alphanumeric code specified for this disposition]]. == Request == === Syntax === setDisposition(dispositionCode); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | dispositionCode | String | Required | The numeric code of the desired disposition | "12345" |} = Set Disposition By Name= Sets the [[#topic_agent-guide/howtoenterdispositionsandnotes|disposition]] for the current interaction by the [[#topic_contact-center-administrator-guide/dispositionstab|name specified of the disposition]]. == Request == === Syntax === setDispositionByName(name); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | name | String | Required | The name of the desired disposition | "Product sold" |} = Set Notes= Sets the [[#topic_agent-guide/howtoenterdispositionsandnotes|free-form notes]] for the current interaction to the specified string. == Request == === Syntax === setNotes(notes); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | notes | String | Required | The interaction notes | "Third time calling today." |} = Set Reporting Custom Field= Allows [[#topic_contact-center-administrator-guide/customreportingfields|custom reporting fields]] to be entered during an agent’s interaction with a customer; the method works like the [[#topic_scenario-builder-reference-guide/setcustomreportingfield|Set Custom Reporting Field]] scenario block. == Request == === Syntax === setReportingCustomField(name, value);'' === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' | '''Example''' |- | name | String | Required | The name of the custom reporting field | "custom1" |- | value | String | Required | The resulting value of the custom reporting field | "$(variable_in_field)" |} = Terminate Interaction= Unlike [[#topic_desktop-javascript-api-specification/completeinteraction|Complete Interaction]], this method only [[#topic_agent-guide/howtoreleaseacall|releases the communication channel]] of the current interaction. For example, if after-call work (ACW) is configured for the corresponding service, interaction processing will continue until ACW is completed. == Request == === Syntax === terminateInteraction(); = Callback= The function that is called upon completion of the call/screen recording methods. == Syntax == callback = function(data) { data.recording = 1/0; data.muted = 1/0; data.paused = 1/0; } === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Description''' | '''Example''' |- | data.recording | Boolean | Indicates if voice/screen recording is currently in progress; note that voice recording is applied to interactions (calls), while screen recording is applied to user sessions | "1" (for true; recording is on) |- | data.muted | Boolean | Indicates if voice recording is currently muted; returned only for the voice recording methods | "0" (for false; recording is not muted) |- | data.paused | Boolean | Indicates if screen recording is currently paused; returned only for the screen recording methods | "1" (for false, recording is not paused) |} = Pause Call and Screen Recording= Mutes call recordings and screen recordings using the following commands. == Mute Call Recordings == Mutes call recording (e.g., when an agent opens a payment screen, a third-party web application loaded into Agent Desktop may issue the JavaScript command). Note that it does not require loading API code on the application's page. === Syntax === parent.frames.postMessage('{"command": "MUTE_CALL_RECORDINGS"}', '*'); == Mute Screen Recordings == Mutes screen recording (e.g., when an agent opens a payment screen, a third-party web application loaded into Agent Desktop may issue the JavaScript command). Note that it does not require loading API code on the application's page. === Syntax === parent.frames.postMessage('{"command": "MUTE_SCREEN_RECORDINGS"}', '*'); = Resume Call and Screen Recording= Uses the following commands to resume a call recording or screen recording that is currently muted. == Unmute Call Recordings == Resumes call recording (e.g., when an agent exits a payment screen, a third-party web application loaded into Agent Desktop may issue the JavaScript command). Note that it does not require loading API code on the application's page. === Syntax === parent.frames.postMessage('{"command": "UNMUTE_CALL_RECORDINGS"}', '*'); == Unmute Screen Recordings == Resumes screen recording (e.g., when an agent exits a payment screen, a third-party web application loaded into Agent Desktop may issue the Javascript command). Note that it does not require loading API code on the application's page. === Syntax === parent.frames.postMessage('{"command": "UNMUTE_SCREEN_RECORDINGS"}', '*'); = Get Call Recording Status= Requests the current status of voice recording of the current call. == Request == === Syntax === getCallRecordingStatus(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Mute Call Recording= Mutes voice recording for the current call. Unlike [[#topic_desktop-javascript-api-specification/stopcallrecording|Stop Call Recording]], this method will continue voice recording for the current call, but any voice signal will be replaced with silence. == Request == === Syntax === muteCallRecording(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Unmute Call Recording= Unmutes the previously [[#topic_desktop-javascript-api-specification/mutecallrecording|muted]] voice recording for the current call. == Request == === Syntax === unmuteCallRecording(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Start Call Recording= Starts voice recording for the current call. For more information, see the Bright Pattern Contact Center ''Agent Guide'', section [[#topic_agent-guide/howtorecordacall|How to Record a Call]]. Note that prior to Bright Pattern Contact Center version 3.8, this method was called ''startCurrentCallRecording();'' and backward compatibility is preserved. == Request == === Syntax === startCallRecording(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Stop Call Recording= Stops voice recording for the current call. Note that prior to Bright Pattern Contact Center version 3.8, this method was called ''stopCurrentCallRecording();'' and backward compatibility is preserved. == Request == === Syntax === stopCallRecording(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Get Screen Recording Status= This function requests the current status of screen recording of the user session. == Request == === Syntax === getScreenRecordingStatus(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Pause Screen Recording= Pauses screen recording of the user session. For the period when screen recording is paused, the recording will contain a static snapshot of the desktop at the moment when pause was applied. == Request == === Syntax === pauseScreenRecording(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Resume Screen Recording= Resumes the previously [[#topic_desktop-javascript-api-specification/pausescreenrecording|paused]] screen recording of the user session. == Request == === Syntax === resumeScreenRecording(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required | Function that will be called upon completion of the method |} = Stop Screen Recording= Stops screen recording of the user session. == Request == === Syntax === stopScreenRecording(callback); === Parameters === {|border="1" style="border-collapse:collapse" cellpadding="5" | '''Parameter''' | '''Type''' | '''Optional/Required''' | '''Description''' |- | [[#topic_desktop-javascript-api-specification/callback|callback]] | Function | Required |Function that will be called upon completion of the method |}