Skip to main content

API

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)​

setTheme (6.18.0)​

Override theme for the current session.

Parameters:

  • theme: 'default' | 'dark'

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