VivochaAgentContact

VivochaAgentContact represents an interaction with a customer from the point of view of an agent. The channel keeps track of all contacts that are visible to the agent, which can be in one of the following top-level states:

  • hidden, the contact is known and visible to the channel (and therefore the agent), but it's currently being proposed to other agents.
  • pending, the contact is queued and the agent is amongst the ones that are expected to accept it. A particular case of a pending contact is contact with property isMine set to true: in this case, the agent must either accept or decline it, failure to do so will result in the agent being transitioned to a forced pause state.
  • assigned, the contact is assigned to agent, who's working on it.
  • terminated, the contact is still in the internal structures of the channel, waiting to be purged. Contacts end up in this state for a variety of reasons, including being abandoned by the customer while queued, being accepted/assigned by other agents and when the communication is over.

Each instance represents a single specific contact, and is responsible for:

Table of Contents

Constructor

new VivochaAgentContact()

Extends

Members

(readonly) idle

Idle state of the contact.

(readonly) isMine

The contact is currently routed only to the agent: can be declined and if it times out, the agent will be put in a forced pause state.

(readonly) mediaState

Overrides:

Current media transition state. The possible values are:

  • init, the contact is still being initialized.
  • idle, no state transition is in progress.
  • offered, an offer was received from the remote and an answer hasn't been sent yet.
  • offering, an offer was sent to the remote and an answer hasn't been received yet.
  • transiting, a media transition is in progress.

(readonly) secure :boolean

Overrides:

Flag set to true is the contact is using end-to-end encryption.

Type:
  • boolean

Methods

setIdle(idle)

Set/Unset the idle state of the contact

Parameters:
Name Type Description
idle boolean

New idle state
Fires:

moveTo(list)

Move the contact to the specified contact list

Parameters:
Name Type Description
list string

One of assigned, pending, hidden.
Fires:

assign(callback)

Assign the contact to the agent, if the operation succeeds, the contact is also moved to the assigned contact list.

Parameters:
Name Type Description
callback GenericCallback

decline(callback)

Decline a pending contact. Only contacts that were routed to a single agent can be declined.

Parameters:
Name Type Description
callback GenericCallback

Called when the operation is completed.

clear(callback)

Clear a pending contact. Only contacts that were routed to the current agent can be cleared.

Parameters:
Name Type Description
callback GenericCallback

Called when the operation is completed.

loadVisit(full, callback)

Downloads from the Vivocha server the details of the current customer visit.

Parameters:
Name Type Description
full boolean

If true all data is retrieved. Otherwise, pageview and event details are omitted.
callback VivochaAgentContact~VisitCallback

The callback to receive the visit data.

updateData(data, callback)

Update the data attached to the contact. NOTE: the remote party is not notified when the update occurs, use a custom request to notify the remote party.

Parameters:
Name Type Description
data DataCollection

The data to save in the contact
callback GenericCallback

Called when the operation is completed.

transfer(opts, callback)

Transfer the contact to another agent or another groups of agents.

Parameters:
Name Type Description
opts object
Properties
Name Type Attributes Description
to string | Array.<string>

Transfer destination info: an agent identifier or an array of tags.
message string <optional>

Optional message that will be relayed to the targets of the transfer.
priority number <optional>

Contact priority.
disableBounceBack boolean <optional>

Disable bounce back in case of no answer.
allowToBusyAgents boolean <optional>

Force transfer to busy agents.
callback GenericCallback

Called when the operation is completed.

setSyncToken(callback)

To Do:
  • add link to docs.vivocha.com

Generate a new synchronization id for the contact.

Parameters:
Name Type Description
callback VivochaAgentContact~SyncCallback

Called when the operation is complete.

isRecording() → {Promise}

Check and returns the recording status of the WebRTC media engine.

Returns:

Resolved with the result of the checks:

  • true if there is an active recording.
  • false if there isn't any active recording.
Type
Promise

startRecording(audioInopt, audioOutopt, videoInopt, videoOutopt) → {Promise}

Start the media recording on the WebRTC media engine for the specified channels.

Examples

Starting audio recording

contact.startRecording(true, true).then(function() {
  console.log('Recording successfully started');
});

Start audio and video recording

contact.startRecording(true, true, true, true).then(function() {
  console.log('Recording successfully started');
});
Parameters:
Name Type Attributes Description
audioIn boolean <optional>

Enable recording for incoming audio.
audioOut boolean <optional>

Enable recording for outgoing audio.
videoIn boolean <optional>

Enable recording for incoming video.
videoOut boolean <optional>

Enable recording for outgoing video.
Returns:

Resolved when the recording is started.

Type
Promise

stopRecording() → {Promise}

Stop the media recording on the WebRTC media engine.

Example

Stopping recording

contact.stopRecording().then(function() {
  console.log('Recording successfully stopped');
});
Returns:

Resolved when the recording is stopped.

Type
Promise

mergeMedia(newMedia) → {Promise}

Overrides:

Merges the passed newMedia with the current media state. This method does not change the media state, it merely returns a description how the current state would be after being merged with the differences listed in newMedia.

Example
// Imagine the current media state (i.e. what contact.getMedia() would return) is:
         {
            "Sharing": {
              "tx": true,
              "rx": true,
              "via": "net",
              "engine": "Native"
            },
            "Chat": {
              "tx": true,
              "rx": true,
              "via": "net",
              "engine": "Native"
            }
         }
      
         // Calling mergeMedia
         contact.mergeMedia({
        "Voice": {
           "tx": true,
           "rx": true,
           "via": "net",
           "engine": "WebRTC"
         }
       })
      
         // The result of mergeMedia
         {
            "Sharing": {
              "tx": true,
              "rx": true,
              "via": "net",
              "engine": "Native"
            },
            "Chat": {
              "tx": true,
              "rx": true,
              "via": "net",
              "engine": "Native"
            },
            "Voice": {
              "tx": true,
              "rx": true,
              "via": "net",
              "engine": "WebRTC"
            }
         }
Parameters:
Name Type Description
newMedia MediaState

The media to merge to the current one.
Returns:

Resolved to the current state merged with newMedia.

Type
Promise

setLocalCapability(path, value) → {Promise}

Overrides:

Set a single local capability. The a capability exchange has already happened, the remote is notified of update.

Parameters:
Name Type Description
path string

Dotted path of the capability to set, "a.b.c"
value *

value, value to set, must be a value that can be converted to string using JSON.stringify.
Returns:

Resolves to a MediaCapabilities object, containing the full set of local capabilities, including the value just set.

Type
Promise

setLocalCapabilities(caps) → {Promise}

Overrides:

Set the local capabilities. The a capability exchange has already happened, the remote is notified of the update.

Parameters:
Name Type Description
caps MediaCapabilities

The new local capabilities
Returns:

Resolves to a MediaCapabilities object, containing the capabilies just set.

Type
Promise

getLocalCapabilities() → {Promise}

Overrides:

Return the local capabilities.

Returns:

Resolves to a MediaCapabilities object.

Type
Promise

getRemoteCapabilities() → {Promise}

Overrides:

Return the local capabilities. If these are not locally available, a capability exchange is started.

Returns:

Resolves to a MediaCapabilities object.

Type
Promise

(async) updateRemoteCapabilities() → {Promise}

Overrides:

Initiate a capability exchange with the remote party: the local capabilities are sent to the remote and its capabilities are requested and returned. After the first time a capability exchange is performed, any change to the local caps is immediately notified to the remote party. Similarly, any change to the remote caps is notified locally via a capabilities event.

Returns:

Resolves to a MediaCapabilities object.

Type
Promise

data() → {ContactData}

Overrides:

Return the raw contact data (i.e. the contact record as stored in Vivocha servers).

Returns:
Type
ContactData

encrypt(text) → {string}

Overrides:

Encrypt the input text using AES256. The contact must be in secure mode.

Parameters:
Name Type Description
text string

The text to encrypt.
Throws:

  • no_crypto: the CryptoJS library couldn't be loaded.

  • invalid_key: the contact is not secure.

Returns:
  • The encrypted and base64 encoded text.
Type
string

encryptMessage(msg, fields) → {object}

Overrides:

Encrypt a message. Only the specified fields are encrypted.

Parameters:
Name Type Description
msg object

The message to encrypt.
fields Array.<string>

List of properties of msg to encrypt.
Throws:

  • no_crypto: the CryptoJS library couldn't be loaded.

  • invalid_key: the contact is not secure.

Returns:

The encrypted message. The list of fields that is added to the massage in the encrypted property.

Type
object

decrypt(data) → {string}

Overrides:

Decrypt the input data using AES256. The contact must be in secure mode.

Parameters:
Name Type Description
data string

Base64 encoded data to decode.
Throws:

  • no_crypto: the CryptoJS library couldn't be loaded.

  • invalid_key: the contact is not secure.

Returns:
  • The plaintext.
Type
string

decryptMessage(msg) → {object}

Overrides:

Decrypt all the encrypted properties of a message.

Parameters:
Name Type Description
msg object

The message to decrypt.
Throws:

  • no_crypto: the CryptoJS library couldn't be loaded.

  • invalid_key: the contact is not secure.

Returns:
  • The decrypted message.
Type
object

sendText(text, langopt, callbackopt)

Overrides:

Send a text message to the remote party

Parameters:
Name Type Attributes Description
text string

Message body
lang string <optional>

ISO 639-1 text language
callback VivochaContact~SendMessageCallback <optional>

Called when the message is sent.
Overrides:

Send a link message to the remote party.

Parameters:
Name Type Attributes Description
url string

URL to send.
desc string <optional>

Description of the link.
callback VivochaContact~SendMessageCallback <optional>

Called when the message is sent.

sendAction(code, argsopt, callbackopt)

Overrides:

Send a custom message to the remote party.

Parameters:
Name Type Attributes Description
code string

User-defined type of message.
args string <optional>

User-defined arguments of the message.
callback VivochaContact~SendMessageCallback <optional>

Called when the message is sent.

sendIsWriting()

Overrides:

Notify the remote party that the local one is composing a new message.

join(callback, force)

Overrides:

Become a partecipant in a contact. For the join to succeed, the contact must have already been assigned to the agent.

Parameters:
Name Type Description
callback GenericCallback

Called when the contact is joined (or if when the join fails)
force boolean

Join the contact even if there's no information on whether it was assigned to the agent. This flag is typically used with third party integrations (e.g. CTI integrations), when an external router assigns the contacts: in this case, the client does not get notified when the assign request succeeds.

leave(reasonopt, callbackopt)

Overrides:

Close all channels and disconnect from a contact.

Parameters:
Name Type Attributes Description
reason string <optional>

Disconnect reason
callback GenericCallback <optional>

Called when the disconnect procedure is over (this includes stopping media acquisition and streaming)

request(type, dataopt, timeoutopt, retriesopt, callbackopt) → {Promise}

Overrides:

Request the remote party to perform an action. This method is used to request a Remote Procedure Call (RPC) over the native communication channel of a Vivocha contact. An action is supported if the contact has a registered event handler for it.

Examples

Requesting a remote to print a document

contact.request('PrintDocument', { name: 'contract.pdf', pages: 'all'}).then(function() {
  console.log('document successfully printed');
});

Implementing a handler for the PrintDocument action

contact.on('PrintDocument', function(data, cb) {
  // print the file
  // call the callback: the first parameter is set in case of error
  // the second is used to resolve the remote promise
  cb(null, true);
});
Parameters:
Name Type Attributes Description
type string

Name of the action to request. Conventionally, type should use camel case and start with a capital letter
data <optional>

Arguments to the action. The data must be serializable using JSON.stringify
timeout number <optional>

Maximum time to wait for an answer, expressed in milliseconds. If omitted, the request never times out.
retries number <optional>

Retry to to the specified number of times. If omitted, only to attempt is performed. Otherwise, timeout out must be specified too.
callback GenericCallback <optional>

Called when the remote answers the request. If omitted, a Promise is returned.
Returns:

Resolved when the remote answers the request. Rejected with

  • timeout if not answer is received in the expected time and all retries have been attempted.
  • not_supported if the remote does not support the specified request type
  • Any other failure defined by the Remote Procedure
Type
Promise

sendData(channel, data, topicopt, typeopt) → {Promise}

Overrides:

Send a custom data packet to the remote party over a DataChannel. If the channel does not already exist, it's created. There's no guaranteed that the remote party is listening for incoming data on the channel: to ensure that, additional messaging between the parties might be required (i.e. sending a request.

Parameters:
Name Type Attributes Description
channel string

The channel name.
data *

The data to send, must be a value that can be converted to string using JSON.stringify.
topic string <optional>

User-defined topic of the message.
type type <optional>

Type of channel to create, leave empty to choose automatically, or specify sio to make sure WebRTC Data Channels are not used.
Returns:

Resolved if the data is sent.

Type
Promise

getDataChannel(id, typeopt) → {Promise}

Overrides:

Return the DataChannel with the given id. If the channel does not already exist, it's created. Type types of channel are supported:

  • WebRTC DataChannel, a peer-to-peer binary data channel between the parties
  • WebSocket channel, a text based channel proxied through the Vivocha servers. Whenever possible, the library will try to use WebRTC channel, to improve the speed and the confidentility of the data transmission. When that is not possible, the library falls back to WebSockets. It's possible to force the use of WebSockets setting the argument type to sio.
Parameters:
Name Type Attributes Description
id string

Channel id/name.
type string <optional>

Pass sio to disable the use of WebRTC.
Returns:

Resolves to the requested DataChannel

Type
Promise

getMediaEngine(id) → {MediaEngine}

Overrides:

Return the media engine with the given id

Parameters:
Name Type Description
id string

Media engine id
Returns:
Type
MediaEngine

registerMediaEngine(engine) → {Promise}

Overrides:

Register a media engine with the contact. Registered engines appear in the capabilities and can be used to negotiate media transitions between parties.

Parameters:
Name Type Description
engine MediaEngine
Returns:

Resolves to the updated media capabilities

Type
Promise

(async) getMedia(clone) → {Promise}

Overrides:

Get the current state of all media.

Parameters:
Name Type Description
clone boolean

clones media to avoid MediaStream objects
Returns:

Resolves to the current MediaState

Type
Promise

getMediaOffer() → {Promise}

Overrides:

Create a media offer from the current media state.

Returns:

Resolved to a MediaOffer

Type
Promise

getMediaState() → {VivochaContact#mediaState}

Overrides:

Get the current media transition state.

Returns:
Type
VivochaContact#mediaState

offerMedia(offer, callbackopt) → {Promise}

Overrides:

Send a media offer to the remote, wait for its answer and, if positive, transition to the new media state.

This method can be called only if the current media transition state is idle.

Parameters:
Name Type Attributes Description
offer MediaOffer

Offer to send
callback VivochaContact~MediaOfferCallback <optional>

The callback to receive the answer. If omitted, the method returns a Promise
Returns:

Resolved to a MediaState, the received answer.

Type
Promise

transitMedia(currentMedia, newMedia, optionsopt) → {Promise}

Overrides:

Initiates a media transition to a new state. Whenever possible, in place of this method, the use of mergeAndTransitMedia is recommended.

This method can be called only if the current media transition state is idle.

Parameters:
Name Type Attributes Description
currentMedia MediaState

The starting/current state of the media
newMedia MediaState

The state to transit to. This state must be complete: any state not included, will be disabled.
options object <optional>
Properties
Name Type Attributes Description
wasOffered boolean <optional>

true if the transition was requested by the remote party.
restore boolean <optional>

true if the transition is to restore a previous media state.
Returns:

Resolved to the final media state at the end of the transition.

Type
Promise

(async) mergeAndTransitMedia(media, optionsopt) → {Promise}

Overrides:

Initiates a media transition to a new state. This method recommended over transitMedia as it lets the caller specify only the media that needs to be changed, as opposed to complete media state.

This method can be called only if the current media transition state is idle.

Parameters:
Name Type Attributes Description
media MediaState

The changes to apply to the current media. All media and property not explicitly specified will retain the current value.
options object <optional>
Properties
Name Type Attributes Description
wasOffered boolean <optional>

true if the transition was requested by the remote party.
restore boolean <optional>

true if the transition is to restore a previous media state.
Returns:

Resolved to the final media state at the end of the transition.

Type
Promise

cloneMedia(media, includeData) → {MediaState}

Overrides:

Create a deep clone of a MediaState object.

Parameters:
Name Type Description
media MediaState

The object to clone.
includeData boolean

If true, the opaque data property is cloned as well, but if one of its properties cannot be cloned (e.g. a native object), a boolean true is set instead.
Returns:

The cloned object.

Type
MediaState

diffMedia(oldMedia, newMedia) → {MediaStateDiff}

Overrides:

Returns the difference between two MediaState objects as a MediaStateDiff.

Parameters:
Name Type Description
oldMedia MediaState

The first state to compare.
newMedia MediaState

The second state to compare.
Returns:

The result of the comparison.

Type
MediaStateDiff

attach(file, descriptionopt, referenceIdopt, callbackopt) → {Promise}

Overrides:

Attach a file to the contacts and send it to the remote party.

Parameters:
Name Type Attributes Description
file File

The file to attach. The argument must be a HTML5 File instance.
description string <optional>

Description of the attachment.
referenceId string <optional>

An opaque reference id of the attachment: the same value will be added to the corresponding attachment event.
callback GenericCallback <optional>

If not specified, a Promise is returned.
Returns:

Resolved when the file is sucessfully uploaded to the Vivocha servers for delivery to the remote.

Type
Promise

Type Definitions

VisitCallback(err, visit)

Parameters:
Name Type Description
err *

Set if an error occurred.
visit VisitData

The current customer visit data.

SyncCallback(err, synchId)

Parameters:
Name Type Description
err *

Set if an error occurred.
synchId string

The new synchronization id.

Events

isidle

The contact has entered the idle state (no activity detected for a the configured "idle chat timeout")

isactive

The contact has entered the active state (activity detected after isidle event)

queuechange

Properties:
Name Type Description
assigned boolean

The contact was moved from or to the assigned contact list.
pending boolean

The contact was moved from or to the pending contact list.
hidden boolean

The contact was moved from or to the hidden contact list.

The contact was moved from one contact list to another.

Type:
  • object

recready

The recorder is not recording and it's ready to start recording.

recstart

The recorder is starting a new recording.

recstarted

The recorder is recording.

recstopping

The recorder is stopping the current recording session.

text

Overrides:

New chat message received.

Parameters:
Name Type Attributes Description
text string

Content of the message.
from_id string

Identifier of the sender.
from_nick string <optional>

Nickname of the message sender.
agent boolean

true if the message was sent by an agent.

localtext

Overrides:

New chat message sent.

Parameters:
Name Type Description
text string

Content of the message.
Overrides:

New link received.

Parameters:
Name Type Attributes Description
url string

URL of the link.
from_id string

Identifier of the sender.
from_nick string <optional>

Nickname of the message sender.
desc string <optional>

Description of the link.
agent boolean

true if the message was sent by an agent.
Overrides:

New link sent.

Parameters:
Name Type Attributes Description
url string

URL of the link.
desc string <optional>

Description of the link.

attachment

Overrides:

New attachment received.

Parameters:
Name Type Attributes Description
url string

URL to download the attachment.
meta object

Attachment metadata.
from_id string

Identifier of the sender.
from_nick string <optional>

Nickname of the message sender.
agent boolean

true if the message was sent by an agent.

iswriting

Overrides:

The remote party is typing a new message.

Parameters:
Name Type Attributes Description
from_id string

Identifier of the sender.
from_nick string <optional>

Nickname of the message sender.
agent boolean

true if the message was sent by an agent.

localiswriting

Overrides:

The local user is typing a message.

ack

Overrides:

The remote party acknowledge the receipt of a message.

Parameters:
Name Type Attributes Description
ref string

Identifier of the message that was ack'd.
from_id string

Identifier of the sender.
from_nick string <optional>

Nickname of the message sender.
agent boolean

true if the message was sent by an agent.

action

Overrides:

Custom message received.

Parameters:
Name Type Attributes Description
action_code string

User-defined type of message.
args Array

User-defined arguments of the message.
from_id string

Identifier of the sender.
from_nick string <optional>

Nickname of the message sender.
agent boolean

true if the message was sent by an agent.

left

Overrides:
Properties:
Name Type Attributes Description
id string

The contact id.
vvcu string <optional>

The unique id of the visitor. If present, it is the customer who left a channel.
user string <optional>

The agent id. If present, it is the agent who left a channel.
reason string <optional>

The reason why the channel was left. Possible reasons are:

  • abandon, the visitor left after waiting in the queue for more than 10 seconds.
  • cancel, the visitor left after waiting in the queue for less than 10 seconds.
  • vvcu, the visitor voluntarily closed the interaction (e.g. closing the widget, pressing end call in a mobile app).
  • user, the agent closed the contact (e.g. pressing the end contact button in the Vivocha Agent Console).
  • timeout, the party failed to ping/communicate with the server for some time .
channels object

Information about the remaining active channels connected to the contact.

Properties
Name Type Attributes Description
total number

Total number of remaining channels.
vvcu number <optional>

Number of remaining channels belonging to the visitor.
user number <optional>

Number of remaining channels belonging to the agent.

One of the media sessions (channels) of the contact has ended. This event can signal that one of the parties has in fact left the contact altogether, or that he simply disabled one of the media. When moving between pages of a website, a customer will leave the connection established on the first page and rejoin the contact on the new page.

Type:
  • object

localleft

Overrides:
Properties:
Name Type Attributes Description
reason string <optional>

The reason why the channel was left. Possible reasons are:

  • abandon, the visitor left after waiting in the queue for more than 10 seconds.
  • cancel, the visitor left after waiting in the queue for less than 10 seconds.
  • closed, the visitor voluntarily closed the interaction (e.g. closing the widget, pressing end call in a mobile app).

The local media session (channel) of the contact has ended. This event signal that the local party has left the contact.

cleared

Overrides:
Properties:
Name Type Attributes Description
id string

The contact id.
reason string <optional>

The reason why the channel was left. Possible reasons are:

  • abandon, the visitor left after waiting in the queue for more than 10 seconds.
  • cancel, the visitor left after waiting in the queue for less than 10 seconds.
  • dissuasion, the visitor was dissuaded by Vivocha after waiting in the queue to the maximum time allowed by the service
  • user, the agent terminated the contact, as no party was left in it
  • disconnect, the party disconnected from the servers

The contact ended.

Type:
  • object

joined

Overrides:
Properties:
Name Type Attributes Description
id string

The contact id.
user string

The agent id.
nick string

The agent's nickname.
avatar object <optional>

The agent's avatar

Properties
Name Type Description
base_url string

Avatar base url
images Array.<object>

Alternative avatar versions

Properties
Name Type Description
size string

Version size
file string

Version file, to be concatenated to the base url

The agent joined the contact.

data

Overrides:
Properties:
Name Type Attributes Description
channel string

The name of the data channel the reiceived the data.
topic string <optional>

Data topic.
data

The received data.

New data was received from a DataChannel.

Type:
  • object

transferred

Overrides:
Properties:
Name Type Description
id string

The contact id.
to object

Destination of the transfer.

Properties
Name Type Attributes Description
toId string

Identifier of the new contact.
toAgent string <optional>

Identifier of the agent the contact was transferred to.
toTags Array.<string> <optional>

List of tags the contact was transferred to.

The contact was transferred to a another agent, to another set of tags or simply requeued

declined

Overrides:
Properties:
Name Type Description
id string

The contact id.
user string

The agent id.
nick string

The agent's nickname.

An agent did not accept a contact that was either transferred or distributed to him.

localcapabilities

Overrides:

The local capabilities changed

Type:

capabilities

Overrides:

The remote capabilities changed (or were received for the first time)

Type:

datachannel

Overrides:

A new DataChannel was created and it's ready to be used.

Type:
  • DataChannel

mediaoffer

Overrides:

A new MediaOffer was received from the remote party.

Parameters:
Name Type Description
offer MediaOffer

The received offer.
callback VivochaContact~MediaOfferCallback

To be called by the handler passing the answer for the remote.

mediachange

Overrides:

The local media state has changed.

Parameters:
Name Type Description
newMedia MediaState

The complete new media state.
diff MediaStateDiff

The difference from the previous state.