Skip to main content
The Reports API lets you extract analytics and historical data from Text, such as chat statistics, agent performance metrics, and trends. This is useful when creating custom reports, building dashboards, or integrating data with external tools. The API gives you raw access to the data to analyze it your way.

When to use the Reports API

Use the Reports API in scenarios where you need to programmatically retrieve Text reports data for analysis or integration. For example:
  • Export data for ad-hoc analysis: You can pull chat metrics (like total chats, first response time, chat ratings) on demand and load them into a spreadsheet or application for deeper analysis.
  • Automate regular reporting: You can script automatic data pulls if you need to generate recurring reports (daily, weekly, monthly) or send scheduled updates.
  • Integrate with BI tools and databases: The API lets you merge Text data with data from other sources. For instance, you can feed Text stats into Google Sheets, Tableau, or Looker Studio to build unified dashboards.
In short, use the Reports API whenever you need direct, flexible access to Text’s reporting data outside of the standard UI for custom analysis or integration.

What this guide covers

  • Authenticating with the Reports API using a personal access token.
  • Ad-hoc and automated data retrieval into Google Sheets through a Google Apps Script.
  • Connect the API to Business Intelligence tools like Tableau Cloud and Looker Studio.

Prerequisites

Before you begin, make sure you have the following:

Personal access token authentication

Before pulling any data, you need to authenticate with the API. The simple approach we will use in this guide is a personal access token (PAT). To generate your PAT, go to Settings → API access → Personal access tokens. Create a new token with the scopes needed for the Reports API endpoints you want to pull. For instance, the Total Chats endpoint requires the reports_read scope. After creating your token, copy the token value, your Account ID, and the Base64 encoded token — you won’t be able to view any of these again after closing the page. Treat your PAT like a password. Do not expose it in client-side code or share it publicly. Use secure storage or environment variables where possible.

Base64 token encoding

Scripts and external tools often require you to parse the token into a Base64 format, where the Account ID is combined with your personal access token: <account_id>:<pat>. The result is used in the HTTP Authorization header as Basic Authentication. Text already returns this encoded value after creating your token.

Ad-hoc data retrieval to Google Sheets

One of the quickest ways to analyze Text data is to pull it into Google Sheets. Before you start, create an empty Google Sheet to hold your data.

Apps Script

Google Apps Script allows you to use JavaScript to manipulate your spreadsheet and call external APIs. To open the script editor, go to Extensions > Apps Script in your created sheet. Before you paste the script, add your personal access token as a script property: navigate to Project Settings > Script Properties and add a property named base64token with your encoded token as the value. Below is a ready-to-use script that allows you to customize the data range, the Reports API endpoints you call, and column header names:
After adding this script, save it and run the pullTextReportData function in the Apps Script editor. Check your Google Sheet — you should see your headers and 30 rows of data.

Script breakdown

  • The script defines configuration values: the sheet name, number of days to go back, and a METRIC_MAP linking column names to API endpoints and JSON paths.
  • It retrieves the Base64-encoded token from script properties for Basic Auth.
  • It calculates the date range for the past 30 days, formatted as ISO timestamp strings.
  • For each metric in METRIC_MAP, it calls the corresponding Reports API endpoint and stores the daily values in byMetric.
  • It writes the resulting table to the Google Sheet, with a frozen header row and auto-resized columns.

Changing endpoints

The METRIC_MAP maps column headers to API endpoint paths:
  • chats/total_chats — the API endpoint (/reports/chats/total_chats)
  • .total — the field in each daily record to extract
To add another property, for example continuous chats from the same endpoint:

Changing the data range

To change the data range, edit the DAYS_BACK value:

Setting a trigger

You can set an automatic trigger to update the data on a schedule. Go to Triggers in the Apps Script editor and create a new trigger for the pullTextReportData function. You can schedule it to run nightly, every X hours, or on sheet open.

Automated no-code options

If you’re not comfortable writing script code, add-ons like API Connector or Apipheny let you configure API calls via a simple interface in Google Sheets. You can also use services like Zapier to connect Text data to Google Sheets.

Connecting the Sheet to Looker

  1. Open Looker Studio > Reports and create a new report.
  2. From the available Google Connectors, choose Google Sheets.
  3. Find and select your sheet, choose the appropriate worksheet, and click Add.
The Data menu on the right will show all fields from your sheet to use in your Looker report.

Connecting to Tableau

  1. Open Tableau Cloud and navigate to New > Virtual Connection.
  2. Select Google Drive from the available connectors and authorize the connection.
  3. Find and select the sheet that holds your data, then click Connect.
  4. Publish the connection and assign it to a project.
You can extend the setup to fit your team’s needs — add more endpoints to METRIC_MAP, adjust the reporting window, or schedule updates more frequently.