VivochaAgentChannel

VivochaAgentChannel, aka the Channel, represents the communication channel between a browser application and the Vivocha servers. The Channel is a singleton and it's automatically instantiated by the vivocha.js library.

The channel is accessed through the function vivocha.channel().

The main responsabilities of the Channel are:

Table of Contents

Constructor

new VivochaAgentChannel()

Extends

Members

(readonly) assignedContacts

List of contacts assigned to the agent.

(readonly) pendingContacts

List of contacts pending/queued for the agent.

(readonly) hiddenContacts

List of contacts known to the channel and still active, but neither assigned nor pending. Usually this list contains contacts that are not yet due to be queued according to the routing settings (e.g. contacts that are currently being proposed to other agents).

(readonly) contacts

Overrides:

Master contact list, contains all contacts known to the channel. Contacts are removed from this list once terminate, completed, transferred or joined by other agents.

Methods

connect(cbopt)

Initiates the connection procedure.

Parameters:
Name Type Attributes Description
cb GenericCallback <optional>

Called when the procedure starts, but before the connection is established.
Fires:

(async) create(ClientContactCreationOptions, ClientContactEventHandler)

Request the Vivocha servers to create a new outbound contact.

Parameters:
Name Type Description
ClientContactCreationOptions object

The parameters for the contact creation.
ClientContactEventHandler object

The handlers for the contact creation.

setNickname(nick)

Temporarily change the nickname of the agent. The new nickname is not stored anywhere and it's only used for the duration of the session.

Parameters:
Name Type Description
nick string

The nickname to temporarily assign to the agent.

setPaused(state)

Using this method, an agent can enter, exit or change the paused state. The pause state is usually represented as a boolean, unless a special/custom state is entered. The only special pause states defined by the library are user (the agent pressed the pause button in the Vivocha Agent Console) and forced (the agent failed to accept an incoming contact that was routed directly to him). More information on the forced pause can be found at this page.

The new state is automatically pushed to server.

The current state can retrieved calling vivocha.get('paused').

Parameters:
Name Type Description
state boolean | string

false to exit the pause state, true or a string to enter it.

setAvailableMedia(state)

Toggle the local agent availability per each media

Parameters:
Name Type Description
state VivochaAgentChannel~MediaAvailability

getAvailableMedia() → {VivochaAgentChannel~MediaAvailability}

Returns an object describing which media the agent can use, and the current state of each

Returns:
Type
VivochaAgentChannel~MediaAvailability

getAgentLoad() → {Promise}

Get the current agent load.

Returns:

Resolved to the current agent load

Type
Promise

sendDeltaLoad(onlyIfChanged, pauseChanged)

Updates the Vivocha servers the current load of the agent. This method is called automatically whenever a change is detected. Call directly only if change in load if caused by events outside of the Vivocha scope, for instance if the agent is using a physical phone to place a direct call.

Parameters:
Name Type Description
onlyIfChanged boolean

Do not send the data to the server if the computed load has changed since the data was last sent to the server.
pauseChanged boolean

If true, the new pause state is propagated to all other active sessions

getContact(id, cbopt) → {Promise}

Returns the requested contact by id. If the contact is not already known to the Channel, it's requested from the Vivocha servers.

Parameters:
Name Type Attributes Description
id string

The contact id
cb VivochaAgentChannel~ContactCallback <optional>

If omitted, a Promise is returned.
Returns:

Resolves to an instance of VivochaAgentContact representing the requested contact

Type
Promise

getContactData(id, cbopt) → {Promise}

Returns the requested contact data by id from the Vivocha servers.

Parameters:
Name Type Attributes Description
id string

The contact id
cb VivochaAgentChannel~ContactCallback <optional>

If omitted, a Promise is returned.
Returns:

Resolves to an instance of VivochaAgentContact.contact representing the requested contact

Type
Promise

getContactFlags(id, cbopt) → {Promise}

Returns the contact's "flags" field.

Parameters:
Name Type Attributes Description
id string

The contact id
cb VivochaAgentChannel~ContactCallback <optional>

If omitted, a Promise is returned.
Returns:

Resolves to an instance of VivochaAgentContact.contact representing the requested contact

Type
Promise

getContactWithKey(id, cbopt) → {Promise}

Returns the requested contact by id. If the contact is not already known to the Channel, it's requested from the Vivocha servers.

Parameters:
Name Type Attributes Description
id string

The contact id
cb VivochaAgentChannel~ContactCallback <optional>

If omitted, a Promise is returned.
Returns:

Resolves to an instance of VivochaAgentContact representing the requested contact

Type
Promise

getContactByExternalKey(id, cbopt) → {Promise}

Returns the requested contact by external id.

Parameters:
Name Type Attributes Description
id string

The contact external id
cb VivochaAgentChannel~ContactCallback <optional>

If omitted, a Promise is returned.
Returns:

Resolves to an instance of VivochaAgentContact representing the requested contact

Type
Promise

getContactDataByExternalKey(id, cbopt) → {Promise}

Returns the requested contact data by external id from the Vivocha servers.

Parameters:
Name Type Attributes Description
id string

The contact external id
cb VivochaAgentChannel~ContactCallback <optional>

If omitted, a Promise is returned.
Returns:

Resolves to an instance of VivochaAgentContact.contact representing the requested contact

Type
Promise

(async) getContacts(ids) → {Promise}

Returns the requested contacts. If the contact is not already known to the Channel, it's requested from the Vivocha servers.

Parameters:
Name Type Description
ids Array.<string>

The ids of the requested contacts
Returns:

Resolves to an array of instances of VivochaAgentContact representing the requested contacts

Type
Promise

getPendingContacts() → {Promise}

Returns all the currently pending contacts that are accessible/visible to the agent.

Returns:

Resolves to an array of instances of VivochaAgentContact

Type
Promise

getMacros(cb) → {boolean}

Retrieves from the servers the list of shortcuts configured and accessible to the agent requesting it.

Parameters:
Name Type Description
cb VivochaAgentChannel~ShortcutListCallback
Returns:

Returns false if no callback was passed.

Type
boolean

getAgentsList(cb) → {boolean}

Retrieves from the servers a list of logged in agents visible to the agent requesting it. The data can be used to build a list of agents a contact can be transferred to.

Parameters:
Name Type Description
cb VivochaAgentChannel~AgentListCallback
Returns:

Returns false if no callback was passed.

Type
boolean

(async) getToken(scopeopt) → {number}

Requests a JWT with the requested scope, or just Token.verify is none is specified.

Parameters:
Name Type Attributes Description
scope string <optional>

The requested scope
Returns:

[expiresIn] - Token expiration in seconds (default 60s)

Type
number

getVerificationToken() → {number}

Requests a verificaton JWT (i.e. a jwt that can only call the /token/verify endpoint).

Returns:

[exp] - Token expiration in seconds (default 60s)

Type
number

ws(type, cmd, queryopt, optsopt) → {Promise}

Overrides:

Invokes a Vivocha V1 REST Web Service. The function uses The fetch() API internally.

Parameters:
Name Type Attributes Description
type string

The type of web service to call
cmd string

The command to execute
query object <optional>

The data to send to the server in the query string.
opts object <optional>

Options with the same format of the init parameter of fetch(). The value of the option credentials is always overridden and set to include.
Returns:

Resolves to the result of the requested Web Service.

Type
Promise

disconnect()

Overrides:

Disconnects the Channel from the Vivocha servers.

isConnected() → {boolean}

Overrides:

Returns the current connection state

Returns:
Type
boolean

Type Definitions

RealTimeStats

Properties:
Name Type Attributes Description
points Array.<VivochaAgentChannel~PointStat>

Top level visitor and agent stats
pages Array.<VivochaAgentChannel~PageStat> <optional>

Stats on the ten currently most visited pages
agents Array.<VivochaAgentChannel~AgentLoadStat> <optional>

Stats on the curretly logged in agents that are visible to the agent receiving the data

PointStat

Properties:
Name Type Attributes Description
ts string

Timestamp of the moment this stat point was recorded.
visitors number

Total number of visitors.
widgets number

Total of visitors seeing a Vivocha widget.
contacts number

Total number of visitors engaging in a Vivocha contact/interaction.
agents number <optional>

Total number of logged in agents.
available_agents number <optional>

Total number of agents available to handle more contacts.

PageStat

Properties:
Name Type Description
url string

The complete URL of a visited page.
title string

Title of the page.
visitors number

Number of visitors on the page.
widgets number

Number of visitors on the page seeing a Vivocha widget.
contacts number

Number of visitors on the page engaging in a Vivocha contact/interaction.

AgentInfo

Properties:
Name Type Attributes Description
id string

The agent's id.
nickname string <optional>

The nickname of the agent.
firstname string <optional>

The firstname of the agent.
surname string <optional>

The surname of the agent.
pic string <optional>

URI of the agent's pic/avatar.
role string <optional>

The agent's role: one of admin, supervisor, agent, auditor.
tags Array.<string> <optional>

List of the agent's tags.

AgentLoadStat

Properties:
Name Type Attributes Description
user_id string

The agent's id.
nickname string <optional>

The nickname of the agent.
firstname string <optional>

The firstname of the agent.
surname string <optional>

The surname of the agent.
pic string <optional>

URI of the agent's pic/avatar.
role string <optional>

The agent's role: one of admin, supervisor, agent, auditor.
tags Array.<string> <optional>

List of the agent's tags.
contacts number

Number of active contacts currently being handled by the agent.
available number

Flag indicating if the agent is currently available to handle more contacts.
available_media Array.<string>

List of media types that are currently enabled. A media will appear in this list if the agent is allowed to use it, he hasn't temporarily disabled and his load allowing him to take on an additional session with that media.
busy_media Array.<string>

List of media types that are enabled, but fully loaded, i.e. the agent won't be able to start an additional session with that media.
media_sessions object

For each enabled media, the number of currently assigned contacts using it

Properties
Name Type Description
audio number

Total number of currently active audio sessions.
video number

Total number of currently active video sessions.
chat number

Total number of currently active chat sessions.
paused boolean | string

Current pause state of the agent.
load number

Current overall load of the agent, from 0 (fully idle) to 1 (fully loaded).

AgentLoad

Properties:
Name Type Description
available_media Array.<string>

List of media types that are currently enabled. A media will appear in this list if the agent is allowed to use it, he hasn't temporarily disabled and his load allowing him to take on an additional session with that media.
busy_media Array.<string>

List of media types that are enabled, but fully loaded, i.e. the agent won't be able to start an additional session with that media.
media_sessions object

For each enabled media, the number of currently assigned contacts using it

Properties
Name Type Description
audio number

Total number of currently active audio sessions.
video number

Total number of currently active video sessions.
chat number

Total number of currently active chat sessions.
load number

Current overall load of the agent, from 0 (fully idle) to 1 (fully loaded).
assigned object

Dictionary of the contacts currently assigned to the agent. For each contact, the object has property with the same name as the contact id containing the following properties.

Properties
Name Type Description
{contact_id} object
Properties
Name Type Description
audio boolean

True is the contact is currently having an audio session.
video boolean

True is the contact is currently having a video session.
chat boolean

True is the contact is currently having a chat session.
assigned_count number

Total number of contacts currently assigned to the agent.
pending object

Dictionary of the contacts currently pending for the agent.

Properties
Name Type Description
{contact_id} object
Properties
Name Type Description
audio boolean

True is the contact is requesting an audio session.
video boolean

True is the contact is requesting a video session.
chat boolean

True is the contact is requesting a chat session.
pending_count number

Total number of contacts currently pending for the agent.
paused boolean | string

Current pause state of the agent.
weights object

For each media, a number from 0 to 1, indicating how a single session affects the agent load. For instance, a value of 0.25 for the chat media indicates that the agent's load will increase by 0.25 per assigned chat session and that the agent can at most handle 4 chats (1/0.25) simultaneously.

Properties
Name Type Description
audio number

Weight of a single audio session.
video number

Weight of a single video session.
chat number

Weight of a single chat session.

ContactCallback(err, contact)

Parameters:
Name Type Description
err *

Set if an error occurred.
contact VivochaAgentContact

The requested contact.

MediaAvailability

Properties:
Name Type Attributes Description
voice boolean <optional>

Local voice availability state
video boolean <optional>

Local video availability state
chat boolean <optional>

Local chat availability state

Shortcut

Properties:
Name Type Attributes Default Description
abbreviation string

The abbreviation that can be used to send the macro to a customer via chat.
content string

The actual content of the shortcut.
type string

The type of content, either text or link.
autorun boolean <optional>
 false

If true, the shortcut is/should be sent automatically at the start of a chat.
key number <optional>

The suggested sorting position of the shortcut, smaller keys should be displayed first.

ShortcutListCallback(err, data)

Parameters:
Name Type Description
err *

Set if an error occurred.
data object
Properties
Name Type Description
macros Array.<VivochaAgentChannel~Shortcut>

The list of shortcuts the agent has access to.

VisibleAgentInfo

Properties:
Name Type Description
id string

The agent id.

AgentListCallback(err, data)

Parameters:
Name Type Description
err *

Set if an error occurred.
data Array.<VivochaAgentChannel~VisibleAgentInfo>

The list of visible logged in agents.

Events

loadchange

The load or the state of the agent changed

Type:

new

A new contact is pending and waiting to be accepted

Type:

joined

Properties:
Name Type Description
id string

Contact id
user string

Id of the agent that accepted the contact (can also be the agent that's receiving the event)

A contact was accepted by an agent

Type:
  • object

cleared

Properties:
Name Type Description
id string

Contact id
reason string

The reason for the contact termination, dissuasion is a possible value.

A contact was terminated. One of the possible reasons is that the customer was dissuaded by Vivocha, as the contact stayed in the pending state for too long.

Type:
  • object

abandoned

Properties:
Name Type Description
id string

Contact id

A contact was abandoned by the customer after waiting for more than 10 seconds.

Type:
  • object

rtstats_v3

New realtime statistics were received. The event is usually received every 20 seconds.

Type:

connecting

Overrides:

The Channel is trying to connect to the first time to the Vivocha servers.

reconnecting

Overrides:

The connection to the Vivocha servers was lost and the Channel is trying to restore it.

connect

Overrides:

The Channel successfully established a connection to the Vivocha servers.

reconnect

Overrides:

The connection to the Vivocha servers was restored.

disconnect

Overrides:

The connection was terminated and it won't be reestablished. This event can be triggered for two reasons: as a result of calling the VivochaChannel.disconnect method and if a lost connection couldn't be restored after the maximum number of attempts.

failed

Overrides:

A connection to the Vivocha servers was not possible. This event is triggered only if a successful connection was never obtained.