most relevant results

developer center results

Connect Gladly to Conversation Intelligence

This feature is only available to paid customers as an add-on. To upgrade, contact your Customer Success Manager or sales@heap.io

Overview

Conversation Intelligence uses Gladly's API to read customer conversation data for analysis. This integration is read-only. Conversation Intelligence doesn't create, edit, or delete data in Gladly.

To set up this integration, you need a dedicated Gladly API user, an API token, your Gladly organization URL, and a csq_eligible topic.

Ingestion scope and eligibility

Channels

The integration ingests the following Gladly channels:

  • Email — The subject, opening message, subsequent replies, and timestamps.
  • Chat and messaging — Each message and its timestamp. This includes Gladly Chat, SMS, WhatsApp, Facebook Messenger, and Instagram Direct.
  • Voice — The transcript of phone calls and voicemails. Gladly voice items don't contain message text, so the recording is transcribed before analysis.

Conversation Intelligence also reads internal notes that agents add to a conversation as part of its history.
 

Eligibility requirements

A successful connection in the Onboarding Wizard does not guarantee that conversations will be ingested. A conversation is eligible for ingestion only when all of the following conditions are met:

  • The conversation has a topic named csq_eligible - all lower case, with an underscore. The match is case-sensitive, so CSQ_Eligible or csq eligible will not match.
  • The topic is top-level and isn't nested under another topic. A nested topic resolves to Parent_csq_eligible, which will not match.
  • The topic was applied within 14 days of the conversation taking place.
  • Creating the topic without applying it to conversations doesn't make those conversations eligible.
Gladly keeps export files for 14 days, so applying the topic to an older conversation may mark it as eligible without leaving Conversation Intelligence any data to read.

Ingestion timing

  • Gladly provides data through export jobs and the Contact Timestamps report.
  • Gladly defaults to a daily export schedule, which runs overnight in UTC. If you need same-day data, contact Gladly Support and request an hourly export schedule before onboarding. Gladly Support is the only team that can make this change.
  • The freshness of data in Conversation Intelligence depends on the Gladly export schedule.

Available history

Gladly keeps export files for 14 days. For older conversations, ask Gladly Support to regenerate the earlier exports as one job per day. This matches the format that Conversation Intelligence ingests. Gladly may charge a service fee for a one-time export covering more than six months.

Required data access

Conversation Intelligence reads the following data from Gladly to reconstruct and analyze conversations:

Data Conversation Intelligence reads How it is used
Conversations and conversation items Provides email, chat, messaging, and voice conversation content, including messages and internal notes.
Call recordings Provides the content of voice conversations and voicemails for transcription and analysis.
Agents Identifies the agents who handled each conversation.
Customers Identifies the customer associated with each conversation.
Topics Identifies conversations marked with csq_eligible.
Inboxes Identifies the inbox assigned to a conversation and any transfers.
Contact Timestamps report Identifies conversations that changed and need to be read.

The API user must have the Agent role and the API User permission. No additional scopes or field-level configuration are required.

Security and setup guidance

  • Use a dedicated API user and token for Conversation Intelligence.
  • Store the API token securely. Gladly displays it only once.
  • Your API token is stored encrypted, and is used only to read the data described on this page.
  • Conversation Intelligence uses the token only to read the data described in this article.
  • Only conversations marked with the csq_eligible topic are analyzed. Other conversations included in Gladly export files are discarded and aren't analyzed or retained.
  • Conversation Intelligence copies voice recordings, stores the audio and transcript, and analyzes the transcript. Contact your Customer Success Manager to enable personal information redaction for voice transcripts.

How to stop the integration

To stop the Gladly integration, revoke or delete the API token associated with the dedicated API user. In Gladly, go to Settings > Users, and select the API user. Then open More settings > API Tokens. Revoking the token immediately stops Heap from reading data. 

Because Gladly does not automatically notify Heap, also contact your Heap Customer Success Manager so the integration can be closed on Heap’s side.

Setup

Step 1: Create the csq_eligible topic

  1. In Gladly, create a topic named csq_eligible exactly and apply it to every conversation you want Conversation Intelligence to analyze.
  2. Make sure the topic is top-level. Don't nest it under another topic.
A successful connection check doesn't confirm that conversations are being ingested. If the topic name doesn't match exactly, is nested under another topic, or hasn't been applied to any conversations, the connection still validates but no conversations are analyzed.

Step 2: Create a dedicated Gladly API user

  1. Sign into Gladly as an Administrator.
  2. Go to Settings > Users.
  3. Create a new user for the Conversation Intelligence integration.
  4. Give the user the Agent role.
  5. Enable the API User permission.
  6. Save the user.

Creating a dedicated user is recommended to manage and audit the integration separately from individual agent accounts.

Step 3: Generate a Gladly API token

  1. Sign in to Gladly as the dedicated API user.
  2. Go to More settings > API Tokens.
  3. Click Create Token.
  4. Copy and securely save the token.

Gladly displays the token only once. If you lose it, generate a new token.

Step 4: Connect Gladly in the onboarding wizard

  1. Open the Conversation Intelligence onboarding wizard.
  2. Select Gladly as the platform.
  3. Enter your Gladly organization URL, for example https://yourcompany.us-1.gladly.com.
  4. Enter the email address of the dedicated API user.
  5. Enter the API token.
  6. Submit the connection details.

Conversation Intelligence validates the connection and checks that it can read a Gladly conversation. After the connection is validated, it begins ingesting conversations marked with the csq_eligible topic.

The initial import of historical conversations runs in the background. The time required depends on the volume of conversations in your Gladly organization.

Last updated
Powered by Zendesk