> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard widgets

> Reference for widget data sources, visualizations, aggregations, and filters

This page is the field reference for building a widget by hand in [Custom dashboards](/analytics/custom-dashboards) — what data you can pull from, how to visualize it, and how to filter it down.

## Data sources

| Source                | Covers                                                                           | Measures you can aggregate              |
| --------------------- | -------------------------------------------------------------------------------- | --------------------------------------- |
| **Calls**             | Phone calls, web voice and avatar sessions, widget live chat, and WhatsApp voice | Calls, Duration, Cost, Successful calls |
| **Assistants**        | Per-assistant conversation counts                                                | Assistants                              |
| **Campaigns**         | Campaign delivery and funnel data                                                | Campaigns, Calls made, Completed leads  |
| **Usage and cost**    | Credit spend over time                                                           | Conversation cost, Conversation minutes |
| **Simulations**       | Assistant test runs and results                                                  | Simulation runs, Evaluation score       |
| **Bookings**          | Calendar bookings created through your assistants                                | Bookings                                |
| **Knowledge sources** | Knowledge base document and crawl-source health                                  | Documents, Knowledge chunks             |

## Visualizations

| Visualization       | Best for                                                               |
| ------------------- | ---------------------------------------------------------------------- |
| **Number**          | One headline figure — a total, a rate, an average                      |
| **Line**            | A trend over time                                                      |
| **Area**            | A trend over time, with the volume underneath emphasized               |
| **Bar**             | Comparing a metric across categories (assistants, campaigns, statuses) |
| **Donut** / **Pie** | A share of one total (outcome mix, sentiment split)                    |
| **Funnel**          | Progress through ordered stages (assigned → called → completed)        |
| **Table**           | Row-level detail rather than a single aggregate                        |

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

| Aggregation | What it computes                                                       |
| ----------- | ---------------------------------------------------------------------- |
| **Count**   | How many records match                                                 |
| **Sum**     | Total of a numeric measure (for example, total duration or total cost) |
| **Average** | Mean of a numeric measure                                              |

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](/api-reference/introduction) for the complete widget schema.