Events API

Use this API to embed uContact inside an external system and communicate with it bidirectionally — subscribe to events fired by uContact and send actions to trigger behavior from your application.

Integration

This section explains how to embed uContact in your external system and set up the communication between both.

Before you begin

By default, uContact only allows external systems to be embedded inside itself. To embed it inside an external system, you must enable the frame-ancestors option and add the URL of the external system.

To integrate uContact into an external system, embed the uContact instance within an iframe. The name attribute is required so you can reference the frame when dispatching actions.

<iframe 
  src="url"
  name="uContact"
  id="uContact"
  scrolling="no" 
  allow="camera;microphone">
</iframe>

Attributes:

• src: The URL of the uContact instance.
• allow: The permissions required for the iframe to access the camera and microphone.

Then add an event listener on the parent window to receive events dispatched by uContact:

window.addEventListener("message", (e) => {
  const { event, data } = e.data;

  switch (event) {
    case "assignedInteraction":
      // Do something
      break;
    case "finishedInteraction":
      // Do something
      break;
    case "sentDisposition":
      // Do something
      break;
    case "changedTheme":
      // Do something
      break;
    case "changedLanguage":
      // Do something
      break;
    default:
      break;
  }
});

Events

These are the events dispatched by uContact. Each event is received as a message on the parent window, with an event field identifying the type and a data field containing the payload.

assignedInteraction

Fired when an interaction is assigned to the agent.

{
  "guid": "string",     // The unique identifier of the interaction
  "campaign": "string", // The campaign name the interaction is associated with
  "channel": "string",  // Channel of the interaction
  "clientId": "string"  // ID of the client
}

finishedInteraction

Fired when an interaction is closed.

{
  "guid": "string",       // The unique identifier of the interaction
  "finishDate": "string"  // The date and time the interaction was closed
}

sentDisposition

Fired when an agent sends a disposition for an interaction.

{
  "guid": "string",         // The unique identifier of the interaction
  "comment": "string",      // The comment of the disposition
  "levelsId": "Array",      // The IDs of the disposition levels selected
  "levelsValue": "Array"    // The values of the disposition levels selected
}

changedTheme

Fired when the user changes the theme of the system.

{
  "dark": "boolean",   // True if the theme is dark
  "primary": "string"  // The primary color of the theme
}

changedLanguage

Fired when the user changes the interface language. The data field is the language code string directly.

"string" // The language code. For example, "en" for English

Actions

Actions let you trigger behavior inside uContact from your external system. Send them using postMessage on the iframe's window object:

window.frames["uContact"].postMessage({ event: "actionName", data: payload }, "*");

startInteraction

Triggers uContact to start a new outbound interaction. The data field contains the information uContact needs to initiate the interaction.

{
  "campaign": "string", // The campaign name the interaction is associated with
  "channel": "string",  // Channel of the interaction
  "clientId": "string"  // ID of the client
}

Example:

window.frames["uContact"].postMessage({
  event: "startInteraction",
  data: {
    campaign: "Sales",
    channel: "telephony",
    clientId: "12345"
  }
}, "*");