Skip to main content

​
Build a custom Insights dashboard

The Insights section ships one fixed hub page plus a set of purpose-built surfaces (retention, funnels, deliverability, LLM spend, and so on). Where those pages stop, the Dashboard Builder starts: it is the no-code composition surface at Insights → Dashboard Builder (/insights/dashboards) that lets you arrange the metrics that already exist behind the per-pillar endpoints into a layout of your own, and share that layout as a signed, embeddable link. This guide covers the builder mechanics — the palette, the grid, widget configuration, layout validation, and the share/embed flow. For how to read the individual Insights surfaces (retention curves, journey paths, topic intelligence, and the rest), see Read the Insights dashboards.

​
What a widget is

Every widget in the palette maps to one read-only metric endpoint the API already serves — message volume, deliverability, voice quality, CDP health, agent QA, LLM spend, burn rate, carbon, and more. The builder never invents a new query: placing a widget means “render the output of that existing endpoint inside my layout.” When the layout is later rendered, each tile fetches its own backing endpoint with the normal authenticated, tenant-scoped request, so a dashboard can never widen the data access the widget’s source endpoint already enforces. Because widgets reference the live endpoint catalog, a widget only exists in the palette when its backing metric is live for your tenant — if a surface you expected is missing, check that pillar’s data is actually flowing.

​
Create a dashboard

  1. Open Insights → Dashboard Builder in the console (visible to the owner, admin, developer, and viewer roles).
  2. Set a Dashboard name and pick the grid column count — 6, 8, 12, 16, or 24 columns. 12 is the default; use more columns when you want finer placement control.
  3. From the Widget palette on the left, click a widget to drop it onto the canvas. The palette groups widgets by category (Messaging, Deliverability, Voice, CDP, Agents, Quality, Spend, Sustainability) and each entry shows its visualization type — stat, line, bar, table, or gauge — so you know what shape the tile will take before you add it. A dashboard can hold up to 50 widgets.
  4. For each placed widget use the editor card on the right to:
    • override the title (leave blank to keep the widget’s own name),
    • adjust width (1 to the column count) and height (1–24 row units) with the steppers,
    • reorder tiles with the up/down controls, or remove them.
  5. When the layout reads right, click Validate layout. Validation is a dry-run against the API: it checks the layout shape, clamps coordinates, de-duplicates tile ids, and confirms every required parameter is set. On success the canvas adopts the normalized layout the server returned.
Your in-progress draft autosaves to this browser’s local storage on every edit, so closing or refreshing the page never loses work. The draft is per-browser — it does not sync across devices or teammates. Clear empties the canvas after a confirmation.

​
Widget parameters

Most widgets accept a window parameter — the look-back window for the metric, one of 24h, 7d, 30d, or 90d — and many also accept a channel filter (sms, whatsapp, rcs, email, voice, telegram). Some widgets bind to a specific object through a required path parameter: the Queue live state widget needs a queue id, the Agent QA scorecard widget an agent id. Required parameters are marked with an asterisk in the widget editor; the canvas warns and the Validate layout button stays disabled until every required value is supplied. Enum-constrained parameters (like window) accept only their listed values — validation rejects anything else.

​
Validate, don’t guess

Validation runs the same normalizer the API uses on a saved or shared layout, so a layout that validates is one the embed renderer will render unchanged. The builder also adopts normalized coordinates back onto the canvas, so what you see after validation is exactly what a recipient of the dashboard will see.

​
Share and embed

Minting a share link is a governance action on the API (the link anyone with the URL can open exposes tenant metrics), so Share & embed is restricted to the owner and admin roles; the button only renders for them, and the API rejects the request for other roles.
  1. Fill in the dashboard name and every required widget parameter (the button stays disabled until those are set).
  2. Click Share & embed.
  3. Pick a lifetime — 1, 7, 30, 60, or 90 days (the default is 30, and the API clamps every request to 1–90 days) — optionally a title override, and Generate link.
  4. Copy either:
    • the Embed URL, which opens a public, white-label page rendering the dashboard, or
    • the Embed snippet, a ready-made <iframe> pointing at that URL to drop into an intranet, portal, or backing-app page.
The signed link embeds the layout snapshot, your tenant scope, and the expiry inline — there is no server-side save step, and the link keeps working until it expires. Anyone with the link can view the dashboard until then; to rotate access you generate a new link (the old one remains valid until its expiry). The embed page renders the composition plus your white-label branding — the named metric tiles laid out on your grid, under your logo and colors — not the live metric values. That page is intentionally view-only: the signed token cannot call authenticated per-widget data endpoints. Use it for “here is the dashboard layout with our branding”, while operators who need live numbers open the builder (or the matching Insights surface) in the console. An invalid, malformed, or expired token returns a friendly “invalid or expired” page (the resolver answers 410/422), a burst of opens answers 429, and any other fault surfaces as a service-unavailable notice — the recipient never sees a raw error.

​
Limits and failure modes

​
Where exports live

The builder itself composes and shares layouts — it is not a data-export surface. If you need a spreadsheet or an image of the numbers, use the export affordance on the individual Insights metric page (for example the Deliverability and Link-tracking surfaces ship CSV/workbook exports), or pull the same endpoints the widgets call through the Analytics API and export from your own tooling. A dashboard link answers “show someone the composition,” not “hand them a file of the data.”

​
How this fits with the other Insights guides

  • Read the Insights dashboards — what each fixed Insights surface answers and how to read it.
  • Insights API reference — the endpoint shapes behind the fixed surfaces (the widget catalog reuses the same read-only family).
  • Scheduled reports — recurring email digests, when you need the numbers pushed to you rather than composed on a page.