# How to Integrate Retool with LiveChat

- Tool: Retool
- Difficulty: Intermediate
- Time required: 20 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to LiveChat by creating a REST API Resource using LiveChat's REST API v3 with Basic Auth (your agent email and a Personal Access Token). Set the base URL to https://api.livechatinc.com/v3.5 and build queries to view chat archives, monitor agent performance, manage agent accounts, and track support queue metrics from a centralized operations dashboard.

## Build a LiveChat Support Operations Dashboard in Retool

LiveChat's native dashboards provide real-time queue monitoring and historical reports, but support operations managers often need custom views that combine LiveChat data with other business systems. You may want to correlate chat volume with product events from your database, build custom SLA compliance reports, or create an agent management panel that shows performance alongside HR data — all scenarios where Retool adds significant value over LiveChat's native reporting.

LiveChat provides a comprehensive REST API (currently v3.5) that exposes chat archives, reports, agent management, and customer data. Authentication uses Basic Auth with your LiveChat agent email and a Personal Access Token that you generate in the developer console. The API uses standard REST conventions with JSON responses and cursor-based pagination for large result sets.

Retool's REST API Resource handles LiveChat's Basic Auth cleanly. Configure it once and build queries for all the LiveChat endpoints your dashboard needs. Build a panel where managers can search chat archives by customer email, view agent performance metrics (first response time, CSAT scores, chats handled), manage agent availability, and monitor queue depth — all from a single Retool interface without needing LiveChat admin access for every team member.

## Before you start

- A LiveChat account with agent or administrator access (API access requires an active LiveChat subscription)
- A LiveChat Personal Access Token (generated at developers.livechat.com → Tools → Personal Access Tokens)
- Your LiveChat account's license number (visible in LiveChat Settings → Account → License number)
- A Retool account with permission to create Resources
- Basic familiarity with Retool's query editor and Table component

## Step-by-step guide

### 1. Generate a LiveChat Personal Access Token

Navigate to developers.livechat.com and sign in with your LiveChat credentials. Go to Tools → Personal Access Tokens. Click Create New Token. Give it a descriptive name like 'Retool Integration' and select the required scopes for your dashboard:

- chats--all:ro — Read access to all chats (required for chat archives)
- agents--all:ro — Read access to agent data (required for agent management)
- reports:ro — Read access to LiveChat reports and analytics
- customers:ro — Read access to customer data

Select only the scopes you need — using the minimum required permissions follows the principle of least privilege.

Click Create Token. Copy the token immediately — it is shown only once. Store it in Retool Settings → Configuration Variables as LIVECHAT_PAT marked as secret.

Also note your LiveChat license number — found in the LiveChat agent app under Settings → Account → License number (or in the URL when logged into the dashboard as a numeric ID). This is not needed for API authentication but is useful for constructing certain report queries.

Personal Access Tokens in LiveChat do not expire by default, but you should rotate them periodically as a security best practice.

**Expected result:** You have a LiveChat Personal Access Token with the appropriate scopes stored in Retool Configuration Variables, and you know your LiveChat license number.

### 2. Create the LiveChat REST API Resource in Retool

In Retool, navigate to the Resources tab and click Add Resource. Select REST API.

Name: LiveChat API

Base URL: https://api.livechatinc.com/v3.5

Authentication: Select Basic Auth.
- Username: your LiveChat agent email address (e.g., agent@yourcompany.com — the same email you use to log into LiveChat)
- Password: your Personal Access Token (the token generated in the previous step, or {{ retoolContext.configVars.LIVECHAT_PAT }} if stored as a Configuration Variable)

Headers:
- Key: Content-Type | Value: application/json
- Key: X-Region | Value: us-1 (or eu-1 for EU-hosted accounts — check your LiveChat account region in Settings → Account)

The X-Region header is required if your LiveChat account is hosted on a regional server. EU-based accounts must use eu-1; US accounts use us-1. Using the wrong region results in 404 errors.

Click Create Resource. Test with a GET to /agents — if it returns a JSON array of your LiveChat agents with their names, emails, and availability status, the connection is working correctly.

**Expected result:** The LiveChat API resource is created and a test GET /agents returns your LiveChat agent list with email addresses, names, and current availability status.

### 3. Fetch agents and build the agent management panel

Create a query named getAgents. Set the method to GET and path to /agents. Optional query parameters:
- fields: id,name,email,permission,workScheduler,groups
- sort_order: desc
- sort: name

The response is an array of agent objects, each with id, name, email, permission (administrator, normal), and groups the agent belongs to.

Create a second query named getAgentDetails triggered when a row is selected: GET /agents/{{ table_agents.selectedRow?.data?.id }}. This returns additional details including login_status (accepting_chats, not_accepting_chats, offline), performance stats, and group memberships.

Create a transformer for the agents list to include formatted permission labels and availability indicators. Bind the transformed data to a Table named table_agents with sortable columns.

To update an agent's status (for admin dashboards), use PATCH /agents/{{ table_agents.selectedRow.data.id }} with a JSON body containing the fields to update. Set this write query to Manual trigger only and wire it to a button with a confirmation modal.

```
// Transformer for LiveChat agents
const agents = data || [];
return agents.map(agent => ({
  id: agent.id,
  name: agent.name || '(Unknown)',
  email: agent.email || '',
  permission: agent.permission || 'normal',
  role: agent.permission === 'administrator' ? 'Admin' : 'Agent',
  login_status: agent.login_status || 'offline',
  status_label: agent.login_status === 'accepting_chats'
    ? 'Online'
    : agent.login_status === 'not_accepting_chats'
    ? 'Away'
    : 'Offline',
  groups: (agent.groups || []).map(g => g.name || g.id).join(', ')
}));
```

**Expected result:** The agents Table shows all LiveChat agents with their names, emails, permission levels, and current availability status with color-coded indicators.

### 4. Fetch chat archives and build the chat search panel

Create a query named getChats. Set the method to GET and path to /chats. LiveChat's archive endpoint supports extensive filtering:

- query: {{ textInput_search.value || '' }} — full-text search across chat content and customer data
- date_from: {{ dateRange.start?.toISOString() }} — ISO 8601 format start date
- date_to: {{ dateRange.end?.toISOString() }} — ISO 8601 format end date
- agent_ids[]: {{ select_agent.value || '' }} — filter by specific agent
- properties.source.customer_email: {{ textInput_email.value || '' }} — filter by customer email
- page_id: {{ nextPageCursor || '' }} — for pagination (LiveChat uses cursor-based pagination)
- limit: 25

The response includes a chats array and a next_page_id cursor for paginating to the next page of results. Each chat object contains id, users (array of customer and agent), thread_summary, tags, and access.

To view a full chat transcript, create a second query getChatTranscript: GET /chats/{{ table_chats.selectedRow?.data?.id }}/threads — this returns the full message history with timestamps.

Create a transformer that extracts customer name/email, agent name, start/end time, duration (in minutes), tags, and CSAT rating from the nested chat object structure.

```
// Transformer for LiveChat archive
const chats = data.chats || [];
return chats.map(chat => {
  const customer = (chat.users || []).find(u => u.type === 'customer') || {};
  const agent = (chat.users || []).find(u => u.type === 'agent') || {};
  const thread = chat.thread_summary || {};
  const start = thread.first_event_created_at ? new Date(thread.first_event_created_at) : null;
  const end = thread.last_event_created_at ? new Date(thread.last_event_created_at) : null;
  const durationMin = start && end
    ? Math.round((end - start) / 60000)
    : null;
  return {
    id: chat.id,
    customer_name: customer.name || '(Unknown)',
    customer_email: customer.email || '',
    agent_name: agent.name || '(Unassigned)',
    started: start ? start.toLocaleString() : '',
    duration_min: durationMin != null ? `${durationMin}m` : '—',
    tags: (chat.access?.group_ids || []).join(', '),
    rating: thread.rating?.score || '—',
    thread_id: thread.id || ''
  };
});
```

**Expected result:** The chat archive panel shows searchable chat history with customer names, agent assignments, chat duration, and CSAT ratings — clicking a row loads the full transcript.

### 5. Build performance reports and queue metrics

LiveChat's Reports API provides pre-aggregated performance data. Create queries to pull key metrics for the management dashboard:

getTotalChats: GET /reports/chats/total-chats with date_from, date_to, and optionally agent_ids[] or group_ids[]. Returns total chat count, missed chats, and abandoned chats broken down by day.

getResponseTimes: GET /reports/chats/first-response-time with the same date parameters. Returns average, max, and min first response times per day — this is the most important SLA metric.

getCSAT: GET /reports/chats/ratings with date parameters and distribution: true to get the rating score distribution (positive vs negative). Returns overall rating and counts.

getAgentActivity: GET /reports/agents/activity with date_from, date_to, and agent_ids[]. Returns hours online, hours accepting chats, and chats handled per agent.

For all report queries, add the date range filter bindings so managers can toggle between today, this week, and this month.

Create a JavaScript query that aggregates data from multiple report endpoints to build a unified KPI summary. Use Promise.all() to run queries in parallel and merge the results.

Display results in Stat components at the top of the dashboard and Bar charts for time-series data. For complex multi-source report dashboards, RapidDev's team can help design the query chaining and data merge architecture.

```
// Transformer for daily chat volume chart
const records = data.records || [];
const sorted = records.sort((a, b) =>
  new Date(a.start).getTime() - new Date(b.start).getTime()
);
return {
  dates: sorted.map(r => new Date(r.start).toLocaleDateString()),
  total: sorted.map(r => r.records?.[0]?.values?.total_chats || 0),
  missed: sorted.map(r => r.records?.[0]?.values?.missed_chats || 0)
};
```

**Expected result:** The dashboard shows KPI stat components with today's total chats, average response time, and CSAT score, plus trend charts showing performance over the selected date range.

## Best practices

- Store the LiveChat Personal Access Token in Retool Configuration Variables (Settings → Configuration Variables) marked as secret — this prevents the token from being visible to Retool app users or less-privileged builders.
- Use scoped Personal Access Tokens with only the permissions your dashboard needs — a reporting dashboard only needs reports:ro and agents--all:ro, not admin-level write access.
- Add pagination to chat archive queries using LiveChat's cursor-based next_page_id system — large accounts may have thousands of chats, and fetching all at once will time out.
- Cache report queries (total chats, response times, CSAT) for at least 5 minutes in the query's Advanced settings — these aggregate metrics don't change in real time and caching significantly reduces API calls.
- Use Retool Workflows instead of in-app queries for scheduled performance reports that need to run outside of business hours — this avoids requiring the Retool app to be open for data to be collected.
- Add row-level color coding to agent status columns using conditional formatting — green for online/accepting, yellow for away, grey for offline — for at-a-glance queue capacity assessment.
- Set all write queries (updating agent status, modifying group assignments) to Manual trigger with a confirmation modal to prevent accidental changes to live support configurations.

## Use cases

### Build an agent performance monitoring dashboard

Create a Retool dashboard showing per-agent metrics: total chats handled, average first response time, average chat duration, CSAT score, and availability hours. Support managers can identify high-performing agents, spot response time trends, and benchmark individuals against team averages.

Prompt example:

```
Build a Retool agent performance dashboard showing all LiveChat agents in a Table with: chats handled today, average response time (seconds), CSAT score, and current availability status. Add a date range filter. Include a Chart showing daily chat volume per agent over the last 14 days. Add stat components for team total chats, team average CSAT, and average response time.
```

### Build a chat archive search and review tool

Create a Retool panel that allows managers to search LiveChat archives by customer email, date range, agent name, or tag. Display the full chat transcript for selected conversations, including customer rating and agent notes. This gives support managers fast access to specific conversations for QA review and escalation handling.

Prompt example:

```
Build a Retool chat archive viewer with search inputs for customer email and date range. Show matching chats in a Table with: customer name, agent name, start time, duration, rating, and tags. When a row is selected, display the full chat transcript in a text area panel on the right side. Include a filter for rated vs unrated chats.
```

### Build a customer support SLA compliance tracker

Create a Retool dashboard that measures SLA compliance across the support team: percentage of chats answered within the target response time, escalations to tickets, and missed chats. Operations teams can monitor compliance in real time and receive alerts when queue thresholds are exceeded.

Prompt example:

```
Build a Retool SLA compliance dashboard for LiveChat. Show daily first response time distribution in a Bar chart. Display a Table of SLA breaches (chats where first response exceeded 60 seconds) with customer details and agent name. Add stat components for today's SLA compliance percentage, missed chats, and average queue wait time.
```

## Troubleshooting

### 401 Unauthorized on all requests despite correct email and PAT

Cause: LiveChat's Basic Auth expects the agent email as the username and the Personal Access Token as the password. If these are swapped, or if a regular password is used instead of a PAT, authentication fails. Also verify the PAT has not been revoked in the LiveChat developer console.

Solution: In the Retool resource Basic Auth settings, confirm Username = your LiveChat agent email (not 'anystring') and Password = your Personal Access Token (not your LiveChat login password). Navigate to developers.livechat.com → Tools → Personal Access Tokens to verify the token still exists and is active. If the token was deleted, generate a new one.

### 404 Not Found for all API endpoints

Cause: The base URL may be using an outdated API version path, or the X-Region header may be pointing to the wrong region for your account. EU-hosted accounts must use the eu-1 region.

Solution: Verify the base URL is https://api.livechatinc.com/v3.5 (not v2 or v3). Check your account region in LiveChat Settings → Account — if it shows an EU location, add X-Region: eu-1 to your resource headers. US accounts use us-1 (the default). Test by calling GET /agents — it should return your agent list if the URL and region are correct.

### Chat archive query returns empty results despite known conversations

Cause: Date range parameters must be in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Passing dates in other formats (e.g., MM/DD/YYYY) causes the filter to be ignored, and the default date range may not include the chats you expect.

Solution: Ensure date_from and date_to are formatted as ISO 8601 strings. Use a Retool DateRange component and bind: {{ dateRange.start?.toISOString() }} for date_from and {{ dateRange.end?.toISOString() }} for date_to. Test with a known date range first by hardcoding a valid ISO date string to confirm the endpoint is accessible.

```
// ISO 8601 date formatting in Retool expression:
// {{ new Date(dateRange.start).toISOString() }}
// Example output: 2024-01-15T00:00:00.000Z
```

## Frequently asked questions

### Does Retool have a native LiveChat connector?

No, Retool does not have a dedicated native LiveChat connector. You connect via a REST API Resource using LiveChat's API key (Personal Access Token) with Basic Auth. The setup takes about 20 minutes and gives full access to the LiveChat REST API for chat archives, agent management, and reports.

### What scopes do I need for a read-only LiveChat analytics dashboard?

For a read-only performance dashboard, request these scopes when creating your Personal Access Token: chats--all:ro (chat archives), agents--all:ro (agent data), and reports:ro (analytics and reports). The customers:ro scope is needed if you want to display customer profile data. Avoid requesting write scopes unless you specifically need to update agent settings or manage configurations from Retool.

### Can I see live chat conversations in real time from Retool?

The LiveChat REST API provides access to historical chat archives, not real-time chat streams. For real-time monitoring, LiveChat provides a separate WebSocket-based Agent Chat API. Retool's standard query system doesn't natively support WebSocket connections, so you'd need a custom component or an intermediate service to relay real-time chat events to Retool. For most management dashboards, the chat archive endpoint with auto-refresh every 30 seconds provides sufficient near-real-time visibility.

### How do I filter chat archives by customer email in Retool?

Use the GET /chats endpoint with a customer search filter. In Retool, create a Text Input component for the email and bind the query parameter properties.source.customer_email to {{ textInput_email.value }}. Set the query to run on trigger (rather than automatically) so it only fires when the user submits the search. The LiveChat API returns all chats associated with that customer email address.

### Can I use Retool to manage LiveChat agent groups and routing rules?

Yes. The LiveChat API supports CRUD operations on agents and groups. GET /groups returns all groups, POST /groups creates a new group, and PATCH /groups/{id} updates group settings. You can build a group management panel in Retool for adding/removing agents from groups and updating routing configurations. These write operations require the agents--all:rw scope on your Personal Access Token.

---

Source: https://www.rapidevelopers.com/retool-integrations/livechat
© RapidDev — https://www.rapidevelopers.com/retool-integrations/livechat