Class

Engagement

Engagement

Members

boolean

# allowedFileContentTypes

Allowed mime types of files that visitor can upload. Example of a value: `['application/pdf', 'image/png']`
boolean

# allowFileSending

Whether visitor can upload and send files.
Chat

# chat

Chat instance connected to this engagement.
Cobrowser

# cobrowser

An object with Cobrowser specific functionality.
string

# createdAt

Timestamp of engagement start in iso8601 format, UTC time zone. Example of value: `2020-06-29T14:43:36.791Z`
number

# engagementId

A unique identifier for the engagement.
object

# EVENTS

Properties:
Name Type Description
COBROWSING_REQUEST string
CUSTOM_COMMAND string
END string
FOCUS string
MEDIA_PERMISSION_REQUEST string
MEDIA_STATE_CHANGE string
MEDIA_UPGRADE_OFFER string
STATE_CHANGE string
WIDGET_MEDIA_UPGRADE_REQUEST string
object

# FOCUS_TARGETS

Properties:
Name Type Description
CHAT string
COBROWSER string
boolean

# isReestablishing

True if the engagement has been re-established false otherwise.
object

# MEDIA_TYPES

Properties:
Name Type Description
TEXT string
AUDIO string
PHONE string
VIDEO string
MediaState

# mediaState

The current media used by the operator and the visitor.

Methods

# addEventListener(type, listener)

Registers an event listener on the engagement. If a listener is added while the engagement is processing an event, it will be not triggered with the current event. If multiple identical listeners are registered on the same event type the duplicate instances are discarded. They do not cause the listener to be called twice and do not need to be removed with the removeEventListener method.
Parameters:
Name Type Description
type string The event type for which the user is registering. Must be one of Engagement#EVENTS.
listener function The listener function that will be called when the event occurs.

# end() → {Promise}

Ends the engagement.
Fulfilled with an empty object or rejected with an Error if the process fails for any reason. The Error may have one of the following causes: INTERNAL_ERROR.
Promise

# getChatTranscript() → {Promise}

Fetch chat transcript of current engagement. Chat transcript will contain all messages that have been exchanged so far.
Fulfilled with an array of OperatorMessage and/or VisitorMessage instances or rejected with an Error if the process fails for any reason.
Promise
Example
var engagementRequest = salemove.requestEngagement('text');

  engagementRequest.engagementPromise.then(function(engagement) {
    engagement.getChatTranscript().then(function(messages) {
      console.log('List of sent chat messages:', messages);
    });
  });

# getSurvey() → {Promise}

Gets engagement Survey.
Fulfilled with a Survey or rejected with an Error
Promise
Example
var engagementRequest = salemove.requestEngagement('text');

  engagementRequest.engagementPromise.then(function(engagement) {
    engagement.addEventListener(engagement.EVENTS.END, function() {
      var gotSurvey = function(survey) {
        var questions = survey.questions;
        // show questions to the visitor
      };

      engagement.getSurvey().then(gotSurvey);
    });
  });

# iframePage(options) → {Promise}

Reloads the current page in an iframe. The page must allow iFraming on the same origin with the X-Frame-Options.
Parameters:
Name Type Description
options Object Iframing options
keptElementSelectors Array.<string> An array of element selectors as defined for document.querySelector to keep attached to the page. All the specified elements, their child elements and parents will be kept in the DOM. All other elements will be removed. All CSS and SCRIPT elements that are required for the engagement widgets must be specified.
Fulfilled with IframedPage or rejected with an Error. The Error may have one of the following causes: INTERNAL_ERROR.
Promise
Example
var engagementRequest = salemove.requestEngagement('text');

  engagementRequest.engagementPromise.then(function(engagement) {
    engagement.iframePage({
      keptElementSelectors: [
        ".important",
        "div#my-sidebar",
        "script[src*='my-javascript']",
        "link[href*='my-css']"
      ]
    }).then(function(iframedPage) {
      engagement.addEventListener(engagement.EVENTS.END, function() {
        iframedPage.deframe();
      });
    });
  });

# notifyOfFocusChange(focusTarget) → {Promise}

Notifies the operator about the part of the application that the visitor is currently focused on. Some applications may choose to de-emphasize or minimize its chat views at times to avoid obstructing the user from browsing the rest of the application. This is particularly relevant on mobile devices where screen space is scarce and chat views often cover the entire screen. (Chat views in this case refer to views that enable both text and audio-visual communication.) Applications that do adopt this behavior should use this endpoint whenever its chat views are either emphasized or de-emphasized. Calling this endpoint with CHAT lets the operator know that the visitor is focused on the chat views of the application and will likely immediately see any messages sent by the operator. Calling it with COBROWSER, however, lets the operator know that the visitor is NOT actively looking at the chat views and may not immediately notice new messages. Applications using this endpoint should also use the FOCUS event to allow the operator to request on the visitor's behalf that the application change focus.
Parameters:
Name Type Description
focusTarget string The part of the application the visitor is currently focused on or which is currently emphasized. Must be one of Engagement#FOCUS_TARGETS.
Fulfilled with an empty object or rejected with an Error if the process fails for any reason. The {Error} may have one of the following causes: INVALID_INPUT, TIMEOUT, INTERNAL_ERROR.
Promise

# recordEvent(options) → {Promise}

Records events generated by an engaged visitor. The activities created by an engaged visitor will be recorded and posted to Glia. If the visitor is engaged with a virtual assistant the events will be processed as regular utterances.
Parameters:
Name Type Description
options object Event options
message string The engaged visitor event.
Fulfilled with an empty object or rejected with an Error if the process fails for any reason. The Error may have one of the following causes: INVALID_INPUT, TIMEOUT, INTERNAL_ERROR.
Promise
Example
var engagementRequest = salemove.requestEngagement('text');

  engagementRequest.engagementPromise.then(function(engagement) {
    var enableRecordEvent = function(engagement) {
      var someButton = document.querySelector('#record-event-button');

      someButton.addEventListener('click', function() {
        engagement.recordEvent({message: 'Record visitor event'});
      });
    };
  });

# removeEventListener(type, listener)

Removes an event listener from the engagement. If an event listener is removed while the engagement is processing an event, it will not be triggered with the current event. An event listener is never invoked after being removed. Calling removeEventListener with arguments which do not identify any currently registered listener has no effect.
Parameters:
Name Type Description
type string The event type for the listener being removed.
listener function The listener to be removed.

# upgrade(options) → {Promise}

Upgrades the engagement media.
Parameters:
Name Type Attributes Description
options object Upgrade options
audio string <nullable>
The audio type to use. Must be one the following: 'browser', 'phone'.
video string <nullable>
The video direction to use. Must be one the following: 'one_way', 'two_way'.
phoneNumber string <nullable>
The visitor's phone number in E.164 format to use when media to upgrade to is 'phone'.
phoneExtension string <nullable>
The visitor's phone number extension, which can contain commas and up to 7 digits. The commas represent a two second wait between digits. This will be used when media is upgraded to 'phone'.
Fulfilled with an empty object or rejected with an Error if the process fails for any reason. The Error may have one of the following causes: INVALID_INPUT, INTERNAL_ERROR, NETWORK_TIMEOUT, NOT_SUPPORTED.
Promise

# uploadFile(file, options) → {Promise}

Uploads a file to an engagement. The uploaded file can be later sent as part of a files attachment.
Parameters:
Name Type Description
file File File instance
options object Upload options
onUploadProgress function Called when upload progresses with {total, loaded} where total signifies the total number of bytes to upload and loaded the number of bytes already uploaded.
Fulfilled with an EngagementFile or rejected with an Error if the upload fails. The {Error} may have one of the following causes: FILE_TOO_LARGE, FILE_CONTENT_TYPE_NOT_ALLOWED, INTERNAL_ERROR, NETWORK_TIMEOUT
Promise
Example
var engagementRequest = salemove.requestEngagement('text');
  var file = new File(['this is the file content'], 'example.txt', {type: 'text/plain'});

  engagementRequest.engagementPromise.then(function(engagement) {
    engagement.uploadFile(file).then(function(response) {
      console.log('ID of uploaded file:', response.id);
    });
  });

Events

# CAPABILITIES

Triggered when the capabilities in this engagement change. The event listener will be called with an EngagementCapabilities instance.

# CUSTOM_COMMAND

Triggered when custom command is triggered when virtual assistant receives custom command response type or when the send custom command endpoint is called. The event listener will be called with an instance of CustomCommand.
Example

Add custom command event listener and access custom command properties

  sm.getApi({ version: 'v1' }).then(function (salemove) {
     var customCommandEventListener = function (engagement) {
       engagement.addEventListener(engagement.EVENTS.CUSTOM_COMMAND, function (customCommand) {
         console.log('custom command properties', customCommand.properties);
       })
    }

    salemove.addEventListener(salemove.EVENTS.ENGAGEMENT_START, customCommandEventListener);
   });

# END

Triggered when this engagement has ended.

# FOCUS

Triggered when operator wants visitor to focus on certain part of the application. The event listener will be called with one of Engagement#FOCUS_TARGETS:

  • CHAT is used when operator wants the visitor to focus on chat area.
  • COBROWSER is used when the operator wants the visitor to focus on cobrowsing area.

# MEDIA_PERMISSION_REQUEST

Triggered when Glia platform requests access to visitor's media device. For example, browser's default media permission prompt can sometimes be hard to notice, so this event can be used to draw visitor's attention to browser's media permission prompt. The event listener will be called with a MediaPermission instance.

# MEDIA_STATE_CHANGE

Triggered when operator or visitor media state changes. The event listener will be called with a MediaState instance.

# MEDIA_UPGRADE_OFFER

Triggered when the operator offers to the visitor the choice of upgrading the engagement to a higher media. Until the offer has not been responded to, neither the operator nor visitor media will change.

The event listener will be called with a MediaUpgradeOffer instance. See MediaUpgradeOffer documentation for examples on how to implement a listener for this event.

# STATE_CHANGE

Triggered when state of the engagement changes. The event listener will be called with an EngagementState instance.

Triggered when an operator requests to CoBrowse with the visitor. Accepting this request means that the operator can fill inputs, click links etc in the visitor's stead. This event might be triggered multiple times. Declining one request does not prevent further requests from being sent by the operator. The event listener will be called with a CobrowsingRequest instance.

# WIDGET_MEDIA_UPGRADE_REQUEST

Triggered when the visitor requests a media upgrade from the visitor's media widget. As explained in the example below, additional information may be asked from the visitor before continuing with the upgrade.

For example, during a 'text' engagement the _microphone button_ is often used to allow upgrades to both `'phone'` and `'audio'` media. When the visitor presses the _microphone button_ this event will be triggered with `'audio'` media and the application usually prompts the user to decide whether they would like to use their phone or their computer's microphone. If they select the phone option they are usually further prompted to provide their phone number. Depending on the design of the application, these prompts could come in the form of modal windows or simple text fields and buttons next to the widget. Because of the large number of interaction options the widget avoids forcing a specific approach and instead allows the application to use any approach that makes most sense in its context.

The event listener will be called with an WidgetMediaUpgradeRequest instance. See its documentation for examples on how to implement a listener for this event.