Skip to content

Dashboard apps

A dashboard app embeds your own web application inside the ChannelX conversation view, giving agents extra context without leaving the screen. You build the app independently and ChannelX surfaces it as a tab — handy for showing a customer's orders, payment history, or any data your systems hold.

When your app loads inside ChannelX, it receives the current conversation and contact as a browser message event. Listen for that event on your page to read the context.

Creating a dashboard app

  1. Go to Settings → Integrations → Dashboard apps and click Configure.
  2. Enter a name for the app and the URL where it's hosted.

A new tab with that name then appears in the conversation window. Opening it loads your app inside the dashboard, where it can fetch and display data scoped to the open conversation.

Receiving context from ChannelX

ChannelX delivers the conversation and contact context as a window message event. Listen for it in your app:

window.addEventListener("message", function (event) {
  if (!isJSONValid(event.data)) {
    return;
  }

  const eventData = JSON.parse(event.data);
});

Requesting data on demand

If you need the latest conversation data at any point, post a message to the parent window using the browser postMessage API. ChannelX listens for the key channelx-dashboard-app:fetch-info and responds with the current conversation payload:

window.parent.postMessage('channelx-dashboard-app:fetch-info', '*')

// The response arrives in your message listener as the appContext payload.

Event payload

The payload your app receives is an appContext event containing three objects:

{
  "event": "appContext",
  "data": {
    "conversation": { /* conversation attributes */ },
    "contact": { /* contact attributes */ },
    "currentAgent": { /* current agent attributes */ }
  }
}

The conversation object includes its id, status, inbox, labels, custom attributes, message history, and a meta block with the sender and assignee. The contact object carries the customer's name, email, phone number, identifier, and any custom or social attributes. The currentAgent object holds the signed-in agent's id, name, and email.

Validate every message

Browser message events can come from any frame. Always confirm the payload is valid JSON, and check the event origin before trusting its contents — never act on unverified input from a postMessage listener.