Integration

The agent bar application is a JavaScript bundle that is inserted directly into the web CRM application. Integration consists of setting parameters using the addition of an object ucsOperator directly into the window object of the browser and include the application itself from UCS server. The application adds methods for its control to the ucsOperator object.

<div id="ucsOperator">Loading agent bar...</div>
<script type="text/javascript">
window.ucsOperator = {
   api: { hostname: 'ucs.zakaznik.cz', port: 443 },
   renderTo: 'ucsOperator',
   headless: false,
   autologin: true,
   listDevices: true,
   confirmDevice: false,
   crmAutoOpen: true,
   onError: crm.agentAppFailed,
   onConnect: crm.agentAppConnected,
   onCredentials: crm.provideCredentials,
   onUser: crm.userInformations,
   onIdentify: crm.telephoneIdentificatorRequired,
   onIdentifier: crm.identifierProvided,
   onDevice: crm.telephonePaired,
   onReady: crm.agentAppReady,
   onStateChange: crm.agentStateChanged,
   onCallRinging: crm.callRinging,
   onCallConnect: crm.callConnected,
   onCallHangup: crm.callHangup,
};
</script>
<script src="https://ucs.zakaznik.cz/operator/operator-v4.0.0.js">

Meaning of parameters

api: obj (v4.0.0)

Websocket proxy address on UCS. If not set, it will be obtained from the current URL.

window.ucsOperator.api = {
   hostname: string,
   port: string,
   path?: string,
   secure?: boolean,
   ws: {
     hostname?: string,
     port?: string,
     path?: string,
     secure?: boolean
   },
   recording: {...}, // same as ws
   report: {...}, // same as ws
   email: {...}, // same as ws
   template: {...}, // same as ws
}

lang: str (v4.0.0)

Default language (before the user logs in).

renderTo: str (v4.0.0)

The ID of the html tag into which the application will be rendered (default “app”).

headless: bool (v4.0.0)

If true, then the GUI will not start at all.

autologin: bool (v4.0.0)

If the login action is used with the 3rd remember parameter set to true, the saving the login name and password in a cookie, the autologin parameter affects, whether the form is only filled out (autologin: false) or the login is also performed (autologin: true)

autologout: bool (v4.0.0)

Automatically log out a user if the same user logs on another computer or in another browser window?

identifyURL: bool (v4.0.0)

Will the identifier passed in the URL be used automatically?

identifyIP: bool (v4.0.0)

Will the IP address obtained by querying the UCS server be used as an identifier?

identifyCookie: bool (v4.0.0)

Will the identifier entered by the user during the previous login be used?

listDevices: bool (v4.0.0)

Whether to get a list of available phones with their pro identifiers from UCS creating a dropdown menu with a selection of phones.

confirmDevice: bool (v4.0.0)

If the parameter is true, the user is prompted to confirm the paired phone according to the specified identifier, when the parameter is set to false, is the application launched immediately after pairing the phone.

showDialControl: bool (v4.0.0)

Should call controls appear in the top bar?

confirmUnload: bool (v4.0.0)

Ask before closing browser tab/window?

notifyWaitingCallers: bool (v4.0.0)

Should agents in ACW or AUX state see a system alert for callers who have entered the queue?

topMenuNameContent: str (v4.0.0)

%name% - display agent name %icon% - show icon

showBottomMenu: bool (v4.0.0)

Should the bottom bar be displayed in the application?

autoOpenAccountCode: bool (v4.0.0)

Should the table for selecting the account code for the call be opened after the call is finished?

audioInputConstraints: AudioInputConstraints (v4.59.0)

Allows you to turn off or on the modification of the sound from the microphone.

interface AudioInputConstraints {
   echoCancellation?: boolean;
   noiseSuppression?: boolean;
   autoGainControl?: boolean;
};

withoutDevice: bool (v4.0.0)

If the parameter is true, then the application will not try to pair the phone after login.

legacyStartup: bool (v4.32.0)

If the parameter is true, then the application does not wait for the browser event 'load', but immediately after loading operator.js it will be executed.

disableIntegratedAutoLogout: bool (v4.32.0)

If the operator application is integrated in another system that performs the login using ucsOperator.sso('username', 'token', 'SomeSystem') method with set third argument, then when the browser tab/window is closed it will be automatic operator logout from UCS. Setting this parameter to true will automatically disables logout.

debounceRequests: bool (v4.34.0)

If this parameter is enabled, the call history will not send a query immediately after changing the filter, but will wait 500 ms if it does not occur another change.

onError: fn (v4.0.0)

A callback that is called by the application in case of an error, e.g. it fails to connect to the server, passing the argument:

• message: str - error text

window.ucsOperator.onError = function(message) {
   console.log('Something went wrong:', message);
}

onWarning: fn (v4.0.0)

A callback that is called by the application in case of an unusual situation, e.g. if on an event or request processing error, passes the argument:

• message: str - warning text

onInfo: fn (v4.0.0)

A callback called by the application in the event of an information message, e.g. a result required changes, passes the argument:

• message: str - information text

onDebug: fn (v4.0.0)

A callback that the application calls in case of a debugging message, e.g. a call notification callback, passes an argument:

• message: str - the text of the debugging message

onMessage: fn (v4.0.0)

A callback called by the application to display a message to the agent, e.g. failed if the agent logs out due to a queue limit, it passes the argument:

• message: obj
  • message: str - message
  • type: enum - message type
    • success
    • info
    • warning
    • error
  • group: str - message type
  • data: obj - other data related to the message

onConnect: fn (v4.0.0)

The callback called by the application after a successful connection to the UCS server passes the argument:

• version: str - application version

onCredentials: fn (v4.0.0)

A callback that the application calls when it requests login data.

onLoginError: fn (v4.0.0)

Callback called in case of login error (e.g. invalid credentials), passes arguments:

• code: int - error code
• message: str - error message

onUser: fn (v4.0.0)

A callback that the application will call at the moment of successful login and loading of information about the logged in user, passes the argument:

• user: obj - parameters of the currently logged in user

onIdentify: fn (v4.0.0)

A callback that the application calls when it requests input from the user identifier for pairing the phone with the PC, passes the argument:

• identifiers: obj - array of objects with a list of phones and their identifiers, if the listDevices parameter is set to true

onIdentifier: fn (v4.0.0)

The callback that the application calls when the identifier is obtained passes the argument:

• identifier: str - PC identifier specified in the URL, obtained from the detected cookie IP address provided by the UCS server or entered by the user

onDevice: fn (v4.0.0)

Callback, which the application calls when the phone is paired with the PC, passes an argument:

• device: obj - information about the currently paired phone

onReady: fn (v4.0.0)

Callback to be called by the application after successful user login, argument passed:

• state (volume)
  • status: enum - agent availability status, same as in onStateChange
  • reason: str - the reason for the agent's absence
  • call: obj - active call on the paired phone
  • user: obj - information about the logged in user
  • device: obj - information about the paired phone
  • auxReasons: obj - reasons for absence
  • callReasons: obj - call reasons (call reason set by the agent after the call ends)
  • queues: obj - available queues
  • groups: obj - list of groups (enum for group_id)
  • agents: obj - list of agents
  • waitingCallers: int - number of people waiting in queues
  • now: timestamp - current UCS time

onStateChange: fn (v4.0.0)

The callback that the application calls when the agent's availability state changes, the argument passed:

• status of order
  • status: enum - agent availability status
    • OFFLINE
    • READY
    • ACW
    • AUX
  • reason: str - reason for absence (AUX)

onCallNew: fn (v4.0.0)

Callback to be called by the application when setting up an outgoing call, argument passed:

• call: obj

onCallRinging: fn (v4.0.0)

Callback to be called by the application on an incoming or outgoing call, argument passed:

• call: obj

onCallConnect: fn (v4.0.0)

Callback to be called by the application when the call is connected, argument passed:

• call: obj

onCallHold: fn (v4.0.0)

Callback to be called by the application when the call is on hold, argument passed:

• call: obj

onCallResume: fn (v4.0.0)

Callback to be called by the application when the held call is resumed, argument passed:

• call: obj

onCallHangup: fn (v4.0.0)

A callback that the application will call when the call ends, the argument passed:

• call: obj

onCallMute: fn (v4.0.0)

The callback that the app calls when the microphone is turned off by the agent, the argument passed:

• call: obj

onCallUnmute: fn (v4.0.0)

Callback to be called by the application when the microphone is turned on by the agent, argument passed:

• call: obj

onAgentSuspend: fn (v4.0.0)

A callback called by the application when the service of one of the queues is interrupted by the agent, primary argument:

• queueId: int - ID of the queue from which the agent should be removed

onAgentResume: fn (v4.0.0)

Callback, which will be called by the application when the service of one of the queues is resumed by the agent, primary argument:

• queueId: int - ID of the queue to which the agent should be returned

onWaitingCallersChange: fn (v4.0.0)

A callback that will be called by the application when the number of people waiting in queues whose member is agent, passed argument:

• waitingCallers: int - number of people waiting in the queue

Component control

At the moment the application initializes (before the onConnect callback is called) adds the following functionality to the window.ucsOperator object. The function can be called in the following states:

• login: CREDENTIALS
• sso: CREDENTIALS
• logout: IDENTIFY, DEVICE, READY
• identifier: IDENTIFY, DEVICE
• provision: IDENTIFY, DEVICE
• identify: DEVICE, READY
• changeStatus: READY
• suspend: READY
• resume: READY
• answer: READY
• dial: READY
• hangup: READY
• transfer: READY
• tribute: READY
• unhold: READY
• notify: any
• state: READY
• selectRingingSound: READY (v4.43.5)

login (v4.0.0)

Agent login, expected arguments:

• username: str - username
• password: str - password
• remember: bool - should the login data be saved in a cookie for the next login?

sso (v4.0.0)

User login using token, expected arguments:

• username: str - username
• token: str - authentication token, viz. SSO
• provider: str - the name of the application that performs the login, if in the layout user there is a tab with the same name, then it is activated

The system into which the application is integrated passes the login agent by calling:

<script type=”text/javascript”>
window.ucsOperator.sso("login.name", "token", "CRM Name");
</script>

This call can only be made based on the onCredentials callback from the application. The token for SSO is generated as an SSHA hash of the SSO preshared secret. Secret is calculated as follows:

token = base64_encode(sha1_hash('secret' + 'username' + 'timestamp') + 'username' + 'timestamp')

Attention! The value from the sha1_hash function is the binary representation of the resulting digest (not its string hexadecimal representation).

After successful agent login, the onReady application calls a callback in which it transmits the agent's current availability status, information about any ongoing call, etc.

logout (v4.0.0)

Unpairing the phone and logging out the agent (no arguments).

selectIdentifier (v4.0.0)

Pairing phone with computer (app), expected argument:

• identifier: str - phone identifier entered in UCS on Device

provision (v4.0.0)

Confirm paired phone, download app settings and get status from UCS (no arguments).

identify (v4.0.0)

Selecting another phone to pair without logging out the user (no arguments).

changeStatus (v4.0.0)

Change agent availability state, expected arguments:

• status: enum - required status
  • OFFLINE
  • READY
  • AUX
  • ACW
• reason: str - reason for absence (AUX)

Agent state change promotion from CRM to CC is done by calling:

<script type="text/javascript">
// ready
window.ucsOperator.changeStatus("READY");

// AUX (not-ready) passing reason
window.ucsOperator.changeStatus("AUX", "Lunch");

// logout from the queue handler
window.ucsOperator.changeStatus("OFFLINE");
</script>

suspend (v4.0.0)

Suspends queue service by the agent, expecting an argument:

• queue: int - ID of the queue in which the service should be suspended

resume (v4.0.0)

Resumes queue handling by the agent, expecting an argument:

• queue: int - ID of the queue in which the service should be restored

answer (v4.0.0)

Picks up the incoming call (no arguments).

dial (v4.0.0)

Click to dial, expected arguments:

• number: str - phone number to be dialed on the agent's phone
• queue: int | "directCall" | "undefined" - ID of the outgoing queue (campaign) under which the outgoing call should be made (optional)
  • "directCall" - no outgoing queue is used for dialing
  • "undefined" - the decision to use the outgoing queue is left to UCS
• line: int - ID of the phone line (device) with which the call is to be made
• data: obj - the metadata that git should attach to the call

The click-to-dial function from CRM to CC is done by calling:

<script type="text/javascript">
window.ucsOperator.dial("0800123456");
</script>

hangup (v4.0.0)

Hang up an ongoing call (no arguments).

Ending an ongoing call from CRM to CC is done by calling:

<script type="text/javascript">
window.ucsOperator.hangup();
</script>

transfer (v4.0.0)

Call transfer, expects an argument:

• number: str - phone number to which the call should be transferred

If the number argument is not passed, it switches to transfer mode (incoming call switched to hold status) and then you need to dial the number another agent (dial method).

If the number argument is entered, then the incoming call will be switched into mode hold and then a consultation call will be made to the specified number.

After a successful connection with the agent (the part of the connection when the person to whom the call is made connected explains the reason for the connection - consultation) the connection is completed with the method finishTransfer to connect the caller to the target agent.

finishTransfer (v4.0.0)

Completing the link with the consultation (no arguments). Transfers the call to another agent, it is called the moment the agents complete the consultation.

blindTransfer (v4.0.0)

Call transfer without consultation, expects one mandatory argument:

• number: str - phone number to which the call should be transferred

tribute (v4.0.0)

Hold (pause) the call (without arguments).

unhold (v4.0.0)

Resume a suspended call (no arguments).

mute (v4.0.0)

Disable/enable the phone's microphone (no arguments). The method works like a toggle.

notify (v4.0.0)

Creates an application notification that is displayed either in the bottom bar of the application or as, for example, with CREDENTIALS state a message of the type "Bad password" immediately below login form inputs.

• title: str - default notification text
• type: str - error, warning, success, info
• unique: bool - if the notification already exists, the older one is deleted
• timeout: int - time after which the notification disappears (null - never)
• boundState: str - the state in which the application will be displayed (null for any)
• group: str - name of the notification group (optional)
• other: obj - other data (e.g. {values {identifier: 'cisco'}} for formatting messages "Bad identifier: {identifier}")

state (v4.0.0)

Returns the current state of the component (the same object as in the onReady callback).

In addition to onReady, the following attributes are available: (v4.55.0)

• ringingSound: 'default' | 'christmas' | 'lovingYou' | 'quest' | 'rush'

setAccountCode (v4.0.0)

Sets the call reason for the call. It expects the following arguments:

• uniqueid: str - unique call ID
• accountCode: str - account code
• subAccountCode: str - second level of account code (default null)
• override: bool - true: overwrite with the specified account code, false: connect the specified code to the existing one (default false)

selectRingingSound (v4.43.5)

Selects the ringtone for the softphone.

Parameters:

• ringingSound: 'default' | 'christmas' | 'lovingYou' | 'quest' | 'rush'

testRingingSound (v4.55.0)

stopRingingSoundTest (v4.55.0)

Structure of objects

Call (v4.0.0)

• called_name: str - called name
• called_number: str - called number
• called_number_norm: str - called number in E.164 format
• caller_channel: str - SIP channel name
• caller_extension: str - caller extension number
• caller_group_id: int - UCS group in which the caller is included
• caller_internal: bool - the caller is an internal PBX extension
• caller_line_id: int - Line ID of the caller's phone
• caller_muted: bool - the caller's microphone is muted
• caller_name: str - name of the caller
• caller_number: str - caller number
• caller_number_norm: str - caller number in E.164 format
• caller_type: enum - caller channel type
  • line: telephone
  • trunk: trunk
• caller_user_id: int - ID of the doorbell user
• caller_username: str - UCS username of the doorbell user
• cause: enum - reason for hanging up the call
  • -1: not set (call not hung up yet)
  • 0: unknown
  • 1: occupied
  • 2: invalid number
  • 3: the caller hung up
  • 4: the called party hung up
  • 5: rejected
  • 6: unavailable
  • 7: pickup
  • 8: transfer
• connected timestamp - call connection time
• connected_channel: str - name of the SIP channel to which the call is connected
• connected_group_id: int - UCS group in which the called party is included
• connected_internal: bool - the PBX internal door is connected
• connected_line_id: int - Line ID of the caller's phone
• connected_muted: bool - the microphone of the called party is turned off
• connected_name: str - name of the connected
• connected_number: str - number to which the call is connected
• connected_number_norm: str - number to which the call is connected in E.164 format
• connected_type: enum - type of channel connected
  • line: telephone
  • trunk: trunk
• connected_user_id: int - ID of the connected user
• connected_username: str - UCS username of the called user
• created timestamp - call creation time
• obj data: call metadata, e.g. what is returned to the UCS server during an external lookup system as a client ID, or other data
• direction: enum
  • OUTGOING: outgoing call
  • INCOMING: incoming call
• disconnected timestamp - time the call was hung up
• external_id: str - ID obtained during caller name lookup
• id int - ID of the active call Attention, rotates in the range 1-65535, for unambiguous use the uniqueid attribute to identify the call!
• name str - if the UCS server in the external system managed to search by numbers name of called/caller
• now timestamp - current UCS time
• number: (string) - number of the called party for an outgoing call or the caller number for an incoming call
• outbound_id: int - Outbound campaign ID
• recorded: bool - whether the call was recorded
• state: enum - call state
  • 0: new
  • 1: connection is in progress
  • 2: invitation
  • 3: connected
  • 4: suspended
  • 5: held (tribute)
• subcalls: int - number of ringing phones (in case of hunt-group)
• uniqueid: str - unique call ID

User {#obj-user} (v4.0.0)

• acwtime: int - time spent in ACW (seconds)
• auxtime: int - time spent in not ready states (seconds)
• auxtimes: obj - times spent in individual times not prepared
  • key: str - AUX name
  • value: int - number of seconds in the given time
• data: obj - custom user data defined in UCS
• displayname: str - displayed name of the user
• email: str - user's email address
• external_id: str - User ID from an external identity provider
• firstname: str - name
• group_id: int - ID of the group to which the user belongs
• id: int - User ID (primary key)
• idletime: int - time when the user was ready but did not speak (seconds)
• in_calls_answered: int - number of connected incoming calls
• in_calls_unanswered: int - number of unanswered incoming calls
• in_ringtime: int - ringing time of incoming agent calls from queues
• in_talktime: int - spoken time of incoming agent calls from queues
• lastname: str - surname
• lines: array - an array of objects containing lines associated with the user
• locale: str - user's language
• number: str - user's external phone number
• out_calls_answered: int - number of connected outgoing calls
• out_calls_unanswered: int - number of unanswered outgoing calls
• out_ringtime: int - ringing time of outgoing agent calls from queues
• out_talktime: int - spoken time of outgoing agent calls from queues
• primary_extension: int - ID of the primary extension if no line login is used
• queues: obj - queues in which the user is included
  • key: int - Queue ID
  • value: obj - parameters and values of the user in the queue
• readytime: int - time spent in ready state (incl. ringing and calls)
• ringtime: int - ringing time of agent calls from queues
• status: enum - agent availability status
  • OFFLINE
  • READY
  • ACW
  • AUX
• superuser: bool - flag whether this is a superuser (admin)
• talktime: int - spoken time of agent calls from queues
• transferred: int - number of transferred agent calls from queues
• transferred_external: int - number of transferred calls outside the CC part of the agent

Queue (v4.0.0)

• answered: int - number of connected calls
• priorities: int - priority of the agent in the queue
• queue_id: int - Queue ID
• ringtime: int - ring time
• supervisor: bool - flag whether this is a supervisor
• suspended: bool - flag whether the agent is suspended from handling calls in the queue
• suspendtime: int - time for which the agent was suspended from handling calls
• talktime: int - talked time
• team_id: int - ID of the team to which the agent belongs
• transferred: int - number of transferred agent calls from queues
• transferred_external: int - number of transferred calls outside the CC part of the agent
• type: enum - queue type:
  • 0: outgoing
  • 1: incoming
• unanswered: int - number of unanswered calls