Class: Engagement

Overview

Events:

END

Triggered when this engagement has ended.

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.

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_STATE_CHANGE

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

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.

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.

WIDGET_MEDIA_UPGRADE_REQUEST

Triggered when the visitor requests a media upgrade from the sm-engaged-visitor 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.

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.

Examples:

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);
 });

Property Summary

(number) engagementId

A unique identifier for the engagement.

(Chat) chat

Chat instance connected to this engagement.

(Operator) operator

(MediaState) mediaState

The current media used by the operator and the visitor.

(Cobrowser) cobrowser

An object with Cobrowser specific functionality.

(boolean) isReestablishing

True if the engagement has been reestablished false otherwise.

(boolean) allowFileSending

Whether visitor can upload and send files.

(boolean) allowedFileContentTypes

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

Variables Summary

SCAN_EVENT_REPLAY_COUNT =
100

Replays are necessary because it is possible that file scan result arrives before the response (which contains the file ID) from upload endpoint is received. This number must be large enough to make sure that events are not missed if a lot of files are uploaded.

EVENTS =
{
  END: 'end',
  STATE_CHANGE: 'state_change',
  MEDIA_UPGRADE_OFFER: 'media_upgrade_offer',
  FOCUS: 'focus',
  MEDIA_STATE_CHANGE: 'media_state_change',
  COBROWSING_REQUEST: 'cobrowsing_request',
  MEDIA_PERMISSION_REQUEST: 'media_permission_request',
  WIDGET_MEDIA_UPGRADE_REQUEST: 'widget_media_upgrade_request',
  CUSTOM_COMMAND: 'custom_command'
}
FOCUS_TARGETS =
{
  CHAT: 'chat',
  COBROWSER: 'cobrowse'
}
MEDIA_TYPES =
{
  TEXT: 'text',
  AUDIO: 'audio',
  PHONE: 'phone',
  VIDEO: 'video'
}

Instance Method Summary

Instance Method Details

# (Promise) upgrade(options)

Upgrades the engagement media.

Parameters:

  • options ( Object )

Options Hash: (options):

  • audio ( ?string ) The audio type to use. Must be one the following: 'browser', 'phone'.
  • video ( ?string ) The video direction to use. Must be one the following: 'one_way', 'two_way'.
  • phoneNumber ( ?string ) The visitor's phone number in E.164 format to use when media to upgrade to is 'phone'.
  • phoneExtension ( ?string ) 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'.

Returns:

  • ( Promise ) — 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) upgrade(media, options)

Deprecated.

Upgrades the engagement to a higher media.

Parameters:

  • media ( string ) The media to upgrade to. Must be one of the following: 'phone', 'audio', 'video'.
  • options ( Object )

Options Hash: (options):

  • phoneNumber ( ?string ) The visitor's phone number in E.164 format to use when media is upgraded to 'phone'.
  • phoneExtension ( ?string ) 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'.
  • oneWay ( ?boolean ) When set to true, only the operator will be upgraded to the requested media, while the visitor's media will remain unchanged. This option is invalid if the specified media is 'phone' or 'audio'. See also: One-Way.

Returns:

  • ( Promise ) — 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) iframePage(options)

Reloads the current page in an iframe.

The page must allow iFraming on the same origin with the X-Frame-Options: https://tools.ietf.org/html/rfc7034.

Examples:

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();
    });
  });
});

Parameters:

  • options ( Object )

Options Hash: (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.

Returns:

  • ( Promise ) — Fulfilled with IframedPage or rejected with an Error. The Error may have one of the following causes: INTERNAL_ERROR.

# (Promise) getSurvey()

Gets engagement Survey.

Examples:

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);
  });
});

Returns:

  • ( Promise ) — Fulfilled with a Survey or rejected with an Error

# (Promise) end()

Ends the engagement.

Returns:

  • ( Promise ) — 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) notifyOfFocusChange()

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:

  • 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.

Returns:

  • ( Promise ) — 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.

# (void) 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:

  • 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.

# (void) 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:

  • type ( string ) The event type for the listener being removed.
  • listener ( function ) The listener to be removed.

# (Promise) recordEvent(params)

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.

Examples:

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'});
    });
  };
});

Parameters:

  • params ( Object )

Options Hash: (params):

  • message ( string ) The engaged visitor event.

Returns:

  • ( Promise ) — 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) uploadFile(file, options)

Uploads a file to an engagement.

The uploaded file can be later sent as part of a files attachment.

Examples:

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);
  });
});

Parameters:

  • file ( File )
  • options ( Object )
  • 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.

Returns:

  • ( Promise ) — 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

    Quickly fuzzy find classes, mixins, methods, file:

    Control the navigation frame:

    You can focus and blur the search input: