Skylight SDK postMessage Communications

The Skylight Software Delivery Kit (SDK) supports front-end messaging between the Skylight interface and third-party applications when Skylight is launched from within the third-party application, such as with a custom customer relationship management application (CRM). The messages are communicated with a postMessage command, which enables cross-origin communication between window objects. For example, Skylight can be opened as a pop-up spawned within a browser window and can enable call controls, agent state controls, and the ability to receive interaction data without requiring development around the Skylight SDK or the use of REST API calls to the platform.

This implementation requires assistance from your software or website development team. If you do not have a developer available, please contact your CxEngage account representative.

Launching Skylight

For postMessage to be able to communicate with a different origin, Skylight must be opened in the parent page:

1
2
3
4
5
skylight = window.open(
  'https://skylight.cxengage.net/?standalonePopup=true&skylightController=true',
  'skylight',
  'width=400,height=800'
);

Initiating Communication

When Skylight has loaded and is ready to start communication, it will post a message with data.topic: 'skylight/loaded'. This is the only postMessage that Skylight performs with targetOrigin: '*'. To set the targetOrigin that Skylight will use for all subsequent messages, the parent page will post { skylightController: true, controllerInit: true } to Skylight. Skylight will use the source on this message as its targetOrigin, and respond with a message with data.topic: 'skylight/target-origin-defined'. This confirms that the secure two-way communication path has been established.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
window.addEventListener('message', event => {
  // Verify Skylight's origin and syntax here
  
  const data = event.data;
  if (data.topic === 'skylight/loaded') {
    // This message tells Skylight to use this event's source for subsequent messages
    skylight.postMessage({
      skylightController: true,
      controllerInit: true
    }, 'https://skylight.cxengage.net');
  } else if (data.topic === 'skylight/target-origin-defined') {
    console.log(
      'Communication with Skylight is secure.' +
      'We can now send messages back and forth.'
    );
  }
});

To receive all other events and messages from Skylight, the same listener as the one above, used to initiate the communication, can be used: 

1
2
3
4
5
6
7
8
9
10
window.addEventListener('message', event => {
  // Same as above code block here
  
  const data = event.data;
  console.log(data.topic, data.error, data.response);
  if (data.topic === 'cxengage/interactions/work-accepted-received') {
    interactionId = data.response.interactionId;
  }
  // More topic/event handling here
});

To post commands to Skylight:

1
2
3
4
5
6
7
8
skylight.postMessage({
  skylightController: true,
  module: 'interactions',
  command: 'endWrapup',
  data:  {
    interactionId
  }
}, 'https://skylight.cxengage.net');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
skylight.postMessage({
  skylightController: true,
  module: 'interactions',
  subModule: 'voice'
  command: 'dial',
  data:  {
    phoneNumber: '+2505550199'
    direction: 'agent-initiated',
    interactionMetadata: {
        campignName: 'Callback Campaign', 
        campaignId: '5738012',
        listName: "Agent 007's List", 
        listId: '7674467',
        listSource: 'Salesforce',
        customer: {
            name: 'John Doe', 
            stateCode: 'AZ', 
            zipCode: '85310'
            country: 'US'
            timezone: 'US/Arizona',
        },
    },
  },
}, 'https://skylight.cxengage.net');

Known issue: Please note that the following commands are not currently fully supported:

If you need any of these, please contact your CxEngage account representative.

Developer Documentation

Complete developer documentation for the modules, commands, and potential error messages is available here.

Demo

Download a demo file here.