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 in Configuration → Security → Allowed domains → Frame ancestors.

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
  "contactId": "string" // ID of the associated contact, if any
}

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
  "finishedByClient": "boolean" // True if the interaction was finished by the client
}

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
  "themeName": "string" // The name of the selected 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

Opens the new outbound interaction form in uContact, prefilled with the information in the data field. The interaction does not start on its own: the agent reviews the form and confirms it. Before opening it, uContact closes the CRM view (if open) and navigates to the Inbox.

If the campaign does not exist or the agent is not a member of it, uContact only shows a notification and does not prefill the form.

{
  "campaign": "string",  // The campaign name the interaction is associated with
  "channel": "string",   // Channel of the interaction
  "clientId": "string",  // ID of the client (phone number, email address, etc.)
  "contact": "string",   // Optional. Alias of clientId; takes precedence if both are sent
  "contactId": "string", // Optional. ID of the contact to associate with the interaction
  "message": "string",   // Optional. Prefilled message text (not applied to telephony)
  "subject": "string"    // Optional. Prefilled subject (email only)
}

Example:

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