= Purpose= The Bright Pattern Contact Center ''Simplified Desktop .NET API Specification'' describes the methods and events of the Simplified Desktop .NET API, which provides access to a number of functions of the Bright Pattern Contact Center Agent Desktop application from .NET-based third-party applications. For more information about the Agent Desktop application, see the Bright Pattern Contact Center [[#topic_agent-guide/Purpose|''Agent Guide'']]. [[#topic_simplified-desktop-net-api-specification/Audience|Next >]] = 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. [[#topic_simplified-desktop-net-api-specification/Purpose|< Previous]] | [[#topic_simplified-desktop-net-api-specification/GeneralInformation|Next >]] = General Information= The API supports the following functions: * Making calls * Getting notifications about initiated calls * Getting notifications about incoming calls * Getting notifications when both outgoing and incoming calls are released * Pausing and resuming voice and screen recordings * Getting notifications when recording is stopped and started The API itself does not replace the softphone functionality; the Bright Pattern Contact Center Agent Desktop application with a softphone (or hardphone) must be running on the user’s computer in order for the API to function. The API communicates with Agent Desktop locally, and therefore, an Agent Desktop session must be started and the softphone plugin (Agent Desktop Helper Application) must be active. The API uses the identity of the user logged into the Agent Desktop application in the current Windows session. [[#topic_simplified-desktop-net-api-specification/Audience|< Previous]] | [[#topic_simplified-desktop-net-api-specification/EventDelivery|Next >]] = Event Delivery= Communications with the softphone plugin are handled by the lowest level of the API; all transport is handled by the .NET platform and all transport-related events are delivered on threads maintained by the platform. Note that direct updating of the UI (either Windows Forms, or WPF) is only permitted on the UI thread--in most cases, the main thread of the application. Although different mechanisms exist to convey execution flow from non-UI to UI threads, the API has its own mechanism that allows receiving events emitted by the API classes on the UI thread--event dispatcher classes. Each API class has a child class named ''eventDispatcher'' (referred to as "event dispatcher"). The event dispatcher class intercepts and re-emits all events emitted by its parent class, while guaranteeing that the events will be delivered on the thread on which the API has been created. Event handlers registered with the API’s event dispatcher class created on the UI thread may directly update elements of the application's UI. All events emitted by all objects follow Microsoft's guideline that asks that all event handlers take two parameters: the object that has emitted the event and another object that encapsulates all arguments of the event. Such an argument object should inherit the ''System.EventArgs'' class and provide any additional data or capabilities in the form of additional properties and methods. All events emitted by the event dispatcher objects carry the reference to the original sender object. [[#topic_simplified-desktop-net-api-specification/GeneralInformation|< Previous]] | [[#topic_simplified-desktop-net-api-specification/APIInstantiationandInitialization|Next >]] = API Instantiation and Initialization= First, the client should create an ''Api'' object and attach event handlers: : m_api = new DesktopControlAPI.ApiLite(); : m_api.eventDispatcher.evtApiUp += this.onApiUp; : m_api.eventDispatcher.evtApiDown += this.onApiDown; : m_api.eventDispatcher.evtCallOffered += this.onCallOffered; : m_api.eventDispatcher.evtCallDialing += this.onCallDialing; : m_api.eventDispatcher.evtCallDisconnected += this.onCallDisconnected; Note that by default API logging is enabled: : ApiLite(bool _enableLog = true); To disable logging, set enableLog to false. : m_api = new DesktopCOntrolAPI.ApiLite(false); Once API is created and event handlers are attached, the client may initialize the API instance: : m_api.InitAPI(); Once API is connected to the softphone and the evtApiUp event is received, the client may dial calls: : m_api.CallDial(“4154556565”); When application terminates the following method should be called to ensure clean termination of the TCP connection between API and the Agent Desktop: : m_api.ShutdownAPI(); [[#topic_simplified-desktop-net-api-specification/EventDelivery|< Previous]] | [[#topic_simplified-desktop-net-api-specification/APIMethods|Next >]] = API Methods= == InitAPI == ''InitAPI'' initializes the API. This request initializes the TCP connection procedure. Once connection is established, the evtApiUp event is sent to the .NET application. === Syntax === bool InitAPI(); == ShutdownAPI == ''ShutdownAPI'' terminates the TCP connection between the API and the Agent Desktop. === Syntax === void ShutdownAPI(); == CallDial == ''CallDial'' initiates a call to the number specified in ''destination''. Specification of the [[#topic_reporting-reference-guide/GlobalInteractionIdentifier|global interaction identifier]] (GIID) is optional. This returns request ID. === Syntax === UInt64 CallDial(string destination, string giid); == MuteCallRecording == ''MuteCallRecording'' mutes audio recording of the call identified by ''callId'' on the given desktop. The recording will continue, but any voice signal will be replaced with silence. === Syntax === UInt64 MuteCallRecording(string callId); == UnmuteCallRecording == ''UnmuteCallRecording'' resumes previously muted audio recording for the call identified by ''callId'' on the given desktop. === Syntax === UInt64 UnmuteCallRecording(string callId); == MuteScreenRecordings == ''MuteScreenRecordings'' mutes screen recording on the given desktop. For the period when screen recording is muted, the recording will contain a static snapshot of the desktop at the moment when mute was applied. This request is processed by the Agent Desktop Helper Application. === Syntax === UInt64 MuteScreenRecordings(); == UnmuteScreenRecordings == ''UnmuteScreenRecordings'' unmutes previously muted screen recording on the given desktop. This request is processed by the Agent Desktop Helper Application. === Syntax === UInt64 UnmuteScreenRecordings(); [[#topic_simplified-desktop-net-api-specification/APIInstantiationandInitialization|< Previous]] | [[#topic_simplified-desktop-net-api-specification/APIEvents|Next >]] = API Events= == evtApiUp == ''evtApiUp'' is sent when the API is successfully connected (or reconnected) to the softphone. Note that no information is provided about calls that already may be present on the Agent Desktop. === Syntax === void evtApiUp(System.EventArgs args); == evtApiDown == ''evtApiDown'' is sent when the ShutdownAPI method is called or when the API loses connection to the softphone. In case of connection loss, the API will try to reconnect every 15 seconds; once reconnected, the ''evtApiUp'' event is sent. === Syntax === void evtApiDown(System.EventArgs args); == evtCallDialing == ''evtCallDialing'' is sent when the softphone starts dialing a call. Note that this event reports calls both initiated by a prior [[#topic_simplified-desktop-net-api-specification/APIMethods|CallDial]] method and dialed directly from the Agent Desktop. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.CallArgs]]. === Syntax === void evtCallDialing(DesktopControlAPI.CallArgs args); == evtCallOffered == ''evtCallOffered'' is sent when the softphone receives a new incoming call. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.CallArgs]]. === Syntax === void evtCallOffered(DesktopControlAPI.CallArgs args); == evtCallDisconnected == ''evtCallDisconnected'' is sent when an existing call is released. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.CallArgs]]. === Syntax === void evtCallDisconnected(DesktopControlAPI.CallArgs args); == onError == ''onError'' is sent when an error occurs while executing a method. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.ErrorEventArgs]]. === Syntax === void onError(DesktopControlAPI. ErrorEventArgs args); == onCallRecordingStarted == ''onCallRecordingStarted'' is sent when call recording is started. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.CallArgs]]. === Syntax === void onCallRecordingStarted(DesktopControlAPI.CallArgs args); == onCallRecordingStopped == ''onCallRecordingStopped'' is sent when call recording is stopped. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.CallArgs]]. === Syntax === void onCallRecordingStopped(DesktopControlAPI.CallArgs args); == onCallRecordingMuted == ''onCallRecordingMuted'' is sent when call recording is muted. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.CallArgs]]. === Syntax === void onCallRecordingMuted(DesktopControlAPI.CallArgs args); == onCallRecordingUnmuted == ''onCallRecordingUnmuted'' is sent when call recording is unmuted. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.CallArgs]]. === Syntax === void onCallRecordingUnmuted(DesktopControlAPI.CallArgs args); == onScreenRecordingStarted == ''onScreenRecordingStarted'' is sent when screen recording is started. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.ScreenRecordingArgs]]. === Syntax === void onScreenRecordingStarted(DesktopControlAPI.ScreenRecordingArgs args); == onScreenRecordingCompleted == ''onScreenRecordingCompleted'' is sent when screen recording is stopped. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.ScreenRecordingArgs]]. === Syntax === void onScreenRecordingCompleted(DesktopControlAPI.ScreenRecordingArgs args); == onScreenRecordingsMuted == ''onScreenRecordingsMuted'' is sent when screen recording is muted. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.BaseEventArgs]]. === Syntax === void onScreenRecordingsMuted(DesktopControlAPI. BaseEventArgs args); == onScreenRecordingsUnmuted == ''onScreenRecordingsUnmuted'' is sent when screen recording is unmuted. For parameters, see the description of auxiliary class [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|DesktopControlAPI.BaseEventArgs]]. === Syntax === void onScreenRecordingsUnmuted (DesktopControlAPI.BaseEventArgs args); [[#topic_simplified-desktop-net-api-specification/APIMethods|< Previous]] | [[#topic_simplified-desktop-net-api-specification/APIProperties|Next >]] = API Properties= == connected == This is used to check if the API is connected to Agent Desktop. It is True if evtApiUp was called before. It is False if evtApiDown was called or evtApiUp was never called. === Type === boolean == calls == This is used to collect calls on the agent’s phone (there may be more than one call). See the description of [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|auxiliary class]] DesktopControlAPI.Call. === Type === System.Collections.Generic.Dictionary <string,DesktopControlAPI.Call> [[#topic_simplified-desktop-net-api-specification/APIEvents|< Previous]] | [[#topic_simplified-desktop-net-api-specification/AuxiliaryClasses|Next >]] = Auxiliary Classes= == DesktopControlAPI.BaseEventArgs == Base event arguments class === Members === * '''reqId''' – Request ID returned by a call that caused the error == DesktopControlAPI.Call == Describes a single phone call === Members === * '''m_id''' – Call ID; string * '''m_direction''' – Call direction; enum; (DesktopControlAPI.CallDirection.Inbound for incoming calls; DesktopControlAPI.CallDirection.Outbound for outgoing calls) * '''m_ANI''' – Caller ID number for incoming calls or agent’s phone number for outgoing calls; string * '''m_DNIS''' – Number dialed by the calling party for incoming calls or number dialed by the agent for outgoing calls; string * '''m_callerName''' – Caller ID text name for incoming calls or agent’s display name for outgoing calls; string * '''m_serviceName''' – Name of the service associated with this call; string * '''m_agentId''' – Agent’s username; string * '''m_agentPhone''' – Agent’s phone number; string == DesktopControlAPI.CallArgs == Class for call attributes used in all call-related events === Members === * '''callId''' – Call ID; string * '''equestId''' – Identifier of the request related to this event; string * '''ANI''' – Caller ID number for incoming calls or agent’s phone number for outgoing calls; string * '''DNIS''' – Number dialed by the calling party for incoming calls or number dialed by the agent for outgoing calls * '''callerName''' – Caller ID text name for incoming calls or agent’s display name for outgoing calls * '''serviceName''' – Name of the service associated with this call * '''attachedData''' – Key-value list of the data attached to this call by the scenario that processed it; scenario should use the [[#topic_scenario-builder-reference-guide/AttachedData|Attached Data]] block for this purpose * '''requestId''' - Optional request ID of the method to which the event responds * '''globalInteractionId''' - [[#topic_reporting-reference-guide/GlobalInteractionIdentifier|Global interaction identifier]] (GIID); string == DesktopControlAPI.ErrorEventArgs == Error event arguments class === Members === * '''reqId''' – Request ID of the method that caused the error * '''callId''' – Call ID; string * '''code''' - Error code * '''description''' - Error description == DesktopControlAPI.ScreenRecordingArgs == Arguments of events related to screen recording === Members === * '''sessionId''' – Screen recording session ID (starting from Bright Pattern Contact Center version 3.9, all agent activities, including interaction handling, are recorded via a single screen recording session; that is, this parameter has no purpose other than backward compatibility) * '''requestId''' - Optional request ID of the method to which the event responds [[#topic_simplified-desktop-net-api-specification/APIProperties|< Previous]]