Messenger Headless Mode SDK

The Messenger Headless Mode SDK allows you to run Messenger without a user interface, providing all service level commands and publishing events, so you can build your own user interface.

In order to build your own Messenger user interface, you will need access to your deployment configuration. For example, when file attachments are disabled, you need to disable the upload button in your Messenger user interface. The deployment configuration looks like the content provided below:

{
   "id":"<String>",  // Contains the Id in UUID format
   "version":"<number>",
   "languages":"<Array>", // An array of selected languages by the end user
   "defaultLanguage": "<String>", // Set to 'en-us' by default
   "apiEndpoint":"<Url>", // For example: https://apps.mypurecloud.com
   "headlessMode": {
      "enabled": "<boolean>"  // Enable or disable headless mode
   },
   "messenger": {
      "enabled": "<boolean>", // Enable or disable messenger
      "apps": {
         "conversations": {
            "messagingEndpoint": "",
            "showAgentTypingIndicator": "<boolean>",       // To show typing activity in Messenger UI.
            "showUserTypingIndicator": "<boolean>",        // To avoid sending user typing events from Messenger.
            "autoStart": {
                "enabled": "<boolean>"                       // Enable or disable autoStart
             }
          }
      },
      "fileUpload": {
         "enableAttachments": "<boolean>",  // Enable or disable Supported Content Profile in web messaging
         "modes": [
            {
               "fileTypes": "<Array>",  //  An array of accepted file types
               "maxFileSizeKB": "<number>"
            }
         ]
      }
   },
   "journeyEvents": {
      "enabled": "<boolean>"  // Enable or disable journey Events
   },
   "auth": {
      "enabled":"<boolean>"  // Enable or disable authentication
   },
   "status": "<String>"
}

There are two ways to access the configuration.

• Command
• GenesysJS.configuration
• Data Model
• GenesysJS.configuration

With the Supported Content Profile in web messaging, configuration published by Messenger can include fileUpload.enableAttachments boolean property in your deployment configuration. When this property is present, the fileUpload.modes array containing the file types must be ignored. And rather an event MessagingService.allowedFileTypes is published that will contain the allowed list of file types in the event data. Please subscribe to this event and read the allowed file types.

For existing deployments that may not be updated with Supported Content Profile yet, fileUpload.enableAttachments property will not be present in the deployment configuration. In this case, the allowed file types must be read from the fileUpload.modes array of your deployment configuration JSON.

Returns the configuration object from config.json.

Resolutions:

Genesys("registerPlugin", "Plugin", function(Plugin) {
Plugin.command("GenesysJS.configuration").then( (data) => { console.log("Deployment configuration", data)} );
});

Published when Messenger fetches the deployment configuration.

Data: Deployment Configuration object.

Genesys("registerPlugin", "Plugin", function(Plugin) {
console.log("config", Plugin.data("GenesysJS.configuration"));
});

Refer to Messaging Service Plugin for commands and events when building your own user interface.

With Headless mode, when the Predictive Engagement is enabled in the Messenger configuration and building your own Engagement user interface, you can re-use the Engagement Plugin commands to let Messenger know what kind of action is performed. This will allow Messenger to send any qualifiedWebMessagingOffer data to our Messaging services automatically.

To implement this, you will write code to subscribe to Journey.qualifiedWebMessagingOffer event and then show your own invite user interface. This event is published by the Journey Plugin based on your configuration.

Genesys("subscribe", "Journey.qualifiedWebMessagingOffer", ({ data }) => {
// write code to show your own Engagement user interface
});

Typically, your custom invite user interface will contain two action buttons Accept and Reject. Hook up the following commands for each button to function accordingly.

• Accept button to accept the invite. When this action is performed, call Engage.accept command.
• Reject button to reject the invite. When this action is performed, call Engage.reject command.

In Headless mode, Co-browse provides the page border and the image of agent's mouse cursor (matching the configured Messenger primary color), but no other UI elements are provided. You are responsible for commands/events/UI just as you would be for a custom messenger in Headless mode.

To build a custom Co-browse toolbar, see the full list of Co-browse events and commands: CobrowseService plugin.

When an agent offers a Co-browse session via a web messaging conversation, a MessengerService.cobrowseOffer event is published. Typically, this is rendered as an invite to join a Co-browse session with "Accept" and "Decline" buttons. Clicking those buttons call CobrowseService.acceptSession and CobrowseService.declineSession accordingly.

Genesys("subscribe", "MessengerService.cobrowseOffer", ({ data }) => {

const joinCode = data.sessionJoinToken;

if (confirm("Do you want to join a Co-browse session?")) {

Genesys("command", "CobrowseService.acceptSession", { joinCode },
// fulfilled callback
() => {
console.log("Co-browse session successfully accepted");
},
// rejected callback
err => {
console.log("could not accept Co-browse session, error code: ", err.code);
});

} else {

Genesys("command", "CobrowseService.declineSession", { joinCode });

}
});

When auto start conversation is enabled in the Messenger configuration, you can establish the WebSocket connection but not start the conversation yet using the MessagingService.configureConversation command. Later when you are ready, use the MessagingService.joinConversation command that will send the JOIN event to start the conversation. Note that this event will be sent only if it is a new conversation session. This can be determined looking at the newSession property that is published in the MessagingService.started event data when the conversation is configured.