Build an extensible reports dashboard in Metabase

This guide is for teams who want Text reports they can customize or connect with their own data. It sets up Metabase, a free, open-source BI tool, backed by a Postgres database you control, so every chart is a SQL query you can edit or extend. By the end of this guide, you’ll have a Metabase dashboard showing your team’s reports data, built on a database that’s open to build on further.

Prerequisites

You’ll need:

Docker and Docker Compose v2, to run Postgres and Metabase.
A Text account with permission to create personal access tokens.
Git, to clone the example repository.

livechat/text-metabase-integration

This guide sets Metabase up and builds the dashboard for you — you don’t need prior Metabase experience to complete it. Familiarity with Metabase (editing questions, adding cards) will help if you want to customize the dashboard afterward.

Use this setup only on your own machine. It stores credentials in a local .env file and doesn’t configure HTTPS. Don’t expose this Metabase instance to the internet or a shared network as-is.

Set up the dashboard

This guide starts a new, local Metabase instance. Three things work together: Text provides the report data, Postgres stores a local copy of it, and Metabase reads that copy and displays the dashboard.

Create a personal access token

In Text, go to Settings → API access → Personal access tokens and create a token with the reports_read scope — this is the permission that lets the exporter read report data. No write access is required.Copy the Base64-encoded token value that Text displays — this is your combined account_id:personal_access_token. The exporter uses this directly as your Text API access.

Treat this value like an equivalent to your account’s API password. Don’t commit it or share it outside a secrets manager.

Clone the repo and configure the environment

In your terminal, clone the repository and copy the example environment file:

git clone https://github.com/livechat/text-metabase-integration.git
cd text-metabase-integration
cp .env.example .env

The .env file holds the settings and credentials this local setup needs. Open the file you just created — in any text editor — and set:

# Base64-encoded Account ID and personal access token from step 1
TEXT_BASIC_AUTH=

# Local Postgres database name and user — the defaults work fine for this quickstart
POSTGRES_DB=text_analytics
POSTGRES_USER=postgres

# Choose any password — this creates a brand-new local Postgres database, so there's nothing to look up
POSTGRES_PASSWORD=secret-password

# Choose an email and password for the local Metabase administrator account — you'll type these same values into Metabase's setup screen in a later step, so they need to match what's here
METABASE_ADMIN_EMAIL=admin@example.com
METABASE_ADMIN_PASSWORD=change-me1

Due to Metabase’s password policy, METABASE_ADMIN_PASSWORD must contain at least one digit.

Start Postgres and Metabase

In your terminal (still inside text-metabase-integration), run:

docker compose up -d

This starts Postgres, which stores the exported report data and Metabase’s own settings. It also starts Metabase itself — the dashboard, at http://localhost:3000 — in the background. You can keep using this same terminal for the rest of the steps.

Export report data

Run the exporter:

docker compose --profile jobs run --rm exporter

This copies the latest 30 days of first response time, CSAT, and chat-duration data from Text into the local Postgres database. When it finishes, the terminal shows export complete. You can run this command again any time you want to refresh the dashboard.

How the export works

This creates the report tables on first run. Then it calls three Reports API v3.6 endpoints for the latest 30 days, measured in UTC, and writes the results to Postgres:

Endpoint	Populates
`POST /reports/agents/performance`	`agent_performance`, `agent_performance_summary`
`POST /reports/chats/ratings`	`chat_ratings`
`POST /reports/chats/duration`	`chat_durations`

Each call sends the same request shape to https://api.livechatinc.com/v3.6, with your Basic-auth credential from step 1:

POST /v3.6/reports/chats/ratings HTTP/1.1
Authorization: Basic <TEXT_BASIC_AUTH>
Content-Type: application/json

{
  "distribution": "day",
  "timezone": "UTC",
  "filters": { "from": "2026-07-11T00:00:00Z", "to": "2026-08-10T00:00:00Z" }
}

agent_performance and agent_performance_summary are fully replaced on every run. They only ever reflect the latest 30-day window, and they hold no history.chat_ratings and chat_durations work differently — they’re saved by date and updated if that date already exists, so their history accumulates across runs. That’s why the dashboard’s “by agent” card only ever shows a current snapshot, while the daily trend cards build up over time.

Complete Metabase's first-run setup

Metabase already has its own database for storing dashboards and settings. This is separate from text_analytics, the database the exporter writes report data into.During first-run setup, complete your initial admin configuration. Metabase will also ask whether you want to add a database — choose “I’ll add my data later”. The next step connects the report data automatically, so adding a database manually here could leave you with a duplicate.Open http://localhost:3000 and step through Metabase’s setup screen using the exact METABASE_ADMIN_EMAIL and METABASE_ADMIN_PASSWORD values from .env.

If you’ve used this local instance before and don’t see the first-run setup screen, reset it with stop or reset.

Bootstrap the dashboard

In a terminal, run:

docker compose --profile jobs run --rm dashboard-bootstrap

This connects Metabase to the local Postgres database and creates the Text Service Quality dashboard with four cards. When it finishes, the terminal shows dashboard bootstrap complete.

How the dashboard connection works

This job signs in with your admin credentials, then:

Finds or creates a Text Analytics Postgres connection pointing at the postgres container.
Finds or creates the Text Service Quality dashboard.
Finds or creates each of four cards on that dashboard, skipping any that already exist — safe to run again after a new export.

The connection details it fills in:

Field	Value
Host	`postgres`
Port	`5432`
Database name	your `POSTGRES_DB` (default `text_analytics`)
Username	your `POSTGRES_USER` (default `postgres`)
Password	your `POSTGRES_PASSWORD`

Each card is a Metabase question built with SQL, run against the exported tables:

-- Overall first response time
SELECT first_response_time_seconds AS seconds
FROM agent_performance_summary
WHERE id = true

-- First response time by agent
SELECT agent_id, first_response_time_seconds AS seconds
FROM agent_performance
WHERE first_response_time_seconds IS NOT NULL
ORDER BY seconds

-- Daily CSAT percentage
SELECT report_date AS day, csat_percent
FROM chat_ratings
WHERE csat_percent IS NOT NULL
ORDER BY day

-- Daily average chat duration
SELECT report_date AS day, average_duration_seconds AS seconds
FROM chat_durations
WHERE average_duration_seconds IS NOT NULL
ORDER BY day

View the dashboard

In Metabase, open Dashboards → Text Service Quality.You should see overall first response time, first response time by agent, daily CSAT, and daily average chat duration — assuming your account had chat activity in the last 30 days.

Troubleshooting

Symptom	Likely cause	Fix
Authentication error	`TEXT_BASIC_AUTH` is incomplete, or the token is missing the `reports_read` scope	Create a new token with the `reports_read` scope and update `.env`
Can’t open Metabase	Docker isn’t running, or the containers didn’t start successfully	Run `docker compose ps` to confirm both containers are running, or `docker compose logs` to check for errors
Exporter can’t connect to Postgres	Postgres hasn’t finished starting, or Docker isn’t running	Run `docker compose ps` to confirm Postgres and Metabase are running, then try the exporter again
Bootstrap can’t sign in	The email or password entered in Metabase’s browser setup doesn’t exactly match `.env`	Check both values against `.env`
Dashboard is empty	No chat activity in the last 30 days on the connected Text account	Confirm there’s recent chat activity, or use an account that has some

Keep the dashboard fresh

The integration does not sync automatically. If you don’t run the exporter again, the dashboard keeps showing the data from the last export:

docker compose --profile jobs run --rm exporter

Run this whenever you want fresh data.

Automate exports on a schedule

If you want this to happen automatically, schedule the command above to run once per day. A crontab entry is the simplest option:

# User crontab (edit with crontab -e) — runs daily at 02:00
0 2 * * * cd /path/to/text-metabase-integration && docker compose --profile jobs run --rm exporter

A scheduled CI workflow can also run the export, but it must use a self-hosted runner that can access the same persistent Docker volumes as the Metabase stack.

Stop or reset

Stop the stack while keeping your data:

docker compose down

Start it again the same way: docker compose up -d. Remove all local data — the exported reports and the Metabase admin account and setup — and start from scratch:

docker compose down -v

Keep exploring

Reports API reference

​Prerequisites

​Set up the dashboard

​Troubleshooting

​Keep the dashboard fresh

​Stop or reset

Prerequisites

Set up the dashboard

Troubleshooting

Keep the dashboard fresh

Stop or reset