Skip to main content
This page is the field reference for building a widget by hand in Custom dashboards — what data you can pull from, how to visualize it, and how to filter it down.

​
Data sources

​
Visualizations

Not every visualization applies to every source — the widget editor only offers the combinations that make sense for the source you picked. For example, Calls supports Number, Line, Area, Bar, Donut, Pie, and Table; Campaigns supports Number, Bar, and Funnel; Usage and cost supports only the time-based views (Number, Line, Area).

​
Aggregations

The editor only offers the aggregations that make sense for what you picked:
  • Category-style visualizations (Bar, Donut, Pie, Funnel, Table) always count records.
  • Sum or Average — call Duration and Cost, Conversation cost, Conversation minutes.
  • Sum only — Calls made, Completed leads, Knowledge chunks.
  • Average only — Successful calls (a success rate) and Evaluation score.
  • Everything else counts records.

​
Grouping and filtering

  • Group by splits an aggregate into a trend or a set of categories. Calls can group by Date, Assistant, Campaign, Status, Direction, Sentiment, Success, or Post-call outcome; Campaigns, Bookings, Knowledge sources, and Simulations group by status (Bookings can also group by source); Usage and cost has no grouping.
  • Filters narrow one widget without touching the rest of the dashboard. They’re available on the Calls source, on the fields with a fixed set of values — Status, Direction, Sentiment, and Success — and the only operator today is is (an exact match), so a live-conversations widget filters Status is In progress.
  • Date range sets the time window: last 7, 14, 30, or 90 days, with an optional comparison to the immediately preceding period of the same length.
  • Assistant scope and Campaign scope limit a widget to one assistant or one campaign. Assistant scope applies to the Calls and Usage sources; campaign scope also applies to Campaigns.

​
API and MCP

Widgets are fully scriptable through the public API — useful for building or migrating dashboards programmatically. The schema accepts a few more values than the in-product editor offers today; a widget built on a combination the dashboard can’t render shows a short note in its place asking you to edit it and pick a supported one, so stick to the combinations above. A widget (POST/PATCH /api/v1/dashboards/{id}/widgets[/{widgetId}], scope dashboards:write) has:
  • widget_type — statistic, chart, or table (the broad shape; visualization picks the specific chart style within it)
  • visualization — auto, number, line, area, bar, stacked_bar, donut, pie, funnel, heatmap, table, or leaderboard
  • data_table — the data source (calls, campaigns, assistants, leads, bookings, knowledge_bases, simulations, tools, phone_numbers, conversions)
  • aggregation — count, sum, avg, max, or min (max and min are API-only today)
  • column_name / group_by — which field to aggregate or group by
  • conditions — up to 20 filters, each a field, an operator (defaults to equals), and a value
  • compare_previous_period, rate_range (7d/14d/30d/90d), show_legend, show_values
  • grid_w (3–12) / grid_h (1–4) — layout size within the dashboard
MCP: create_dashboard_widget, update_dashboard_widget, remove_dashboard_widget, list_dashboard_widgets. See the API reference for the complete widget schema.