Connect Gorgias to Conversational Intelligence

Use this guide to connect your Gorgias account to Heap Conversation Intelligence through OAuth 2.0. After the connection is complete, Conversation Intelligence reads selected Gorgias data to ingest and analyze supported conversations.

Conversation Intelligence uses read-only access. It doesn't create, edit, tag, close, or delete anything in your Gorgias account. Conversation Intelligence reads the Gorgias REST API directly. There is no file export, data feed for you to schedule, or data pushed from Conversation Intelligence into Gorgias.

Overview

A Gorgias ticket becomes one conversation in Conversation Intelligence. A phone ticket with several recordings becomes one conversation per recording.

Conversation Intelligence reads the following data from Gorgias:

How the connection works

Conversation Intelligence connects to Gorgias as an app through OAuth 2.0. A Gorgias administrator approves the connection on the Gorgias consent screen. You don't need to create a dedicated API user, generate an API key, or paste a token into Heap.

Complete these four steps:

1. Create the csq_eligible tag and apply it to the tickets you want to analyze. 
2. Choose the channels you want to ingest.
3. Provide your Gorgias account URL.
4. Approve Conversation Intelligence's read-only access on the Gorgias consent screen.

Your Gorgias administrator should complete these steps. Conversation Intelligence checks the approval immediately, and onboarding validation can run after the approval succeeds.

The Heap team handles the integration's installation and ingestion schedule. You don't need to configure those settings.

Before you connect

Make sure you have the following ready:

• Administrator access to your Gorgias account.
• A list of the channels you want to ingest. The onboarding wizard offers Chat, Email, and Voice.
• The csq_eligible tag, created with the exact spelling and capitalization described below in Step 1. 
• Your Gorgias account URL, in the format described below.

Set up the connection

Step 1: Create the csq_eligible tag

Create a Gorgias tag named exactly csq_eligible, then apply it to every ticket you want Conversation Intelligence to analyze. The tag name is case-sensitive. Use lowercase letters, one underscore, no spaces, and no prefix or suffix.

The tag must exist before onboarding validation runs. If Conversation Intelligence can't find it, validation stops and onboarding can't proceed.

If validation can't find the tag, you may see the following message:

Cannot onboard yet - Conversation Intelligence uses the csq_eligible tag to know which conversations to ingest, and it isn't queryable yet. Ask your platform administrator to set it up according to the onboarding guide, then re-run.

Gorgias's tag search is case-insensitive, but Conversation Intelligence compares the tag name exactly after it retrieves it. A tag named CSQ_Eligible or CSQ_ELIGIBLE therefore doesn't meet the requirement.

Removing the tag later doesn't withdraw a conversation that has already been ingested. If you need to exclude a conversation after it has been tagged, contact your Heap Customer Success Manager.

Conversation Intelligence looks for one tag by exact name. It doesn't apply nesting, hierarchy, or parent-tag rules.

Step 2: Choose the channels to ingest

In the onboarding wizard, select the channels you want to see in Conversation Intelligence: Chat, Email, and, if applicable, Voice. Select Voice only if it is in scope for your program. Your channel selection can't be changed after onboarding is activated.

The channel behavior is described in Supported channels. Selecting Voice also has a commercial implication because it places the program on premium voice.

Step 3: Provide your Gorgias account URL

Your Gorgias account URL must use this format:

https://<your-subdomain>.gorgias.com

For example:

https://acme.gorgias.com

The URL must meet all of the following requirements:

• Use https.
• Contain no username or password.
• Contain no path, query string, or fragment. Enter only the host.
• End in .gorgias.com.

Step 4: Approve access on the Gorgias consent screen

After you enter the account URL, the onboarding wizard sends you to an approval page in your Gorgias account. A Gorgias administrator must review and approve the request.

Conversation Intelligence requests the following read-only scopes:

Reading your account's tags is covered by the approved access and isn't listed as a separate consent-screen item. You don't need to configure a permission matrix or grant field-level access.

If approval is interrupted or the wrong person starts the process, repeat this step.

Supported channels

Gorgias serves chat, email, SMS, and social channels through a shared ticket API. When Chat or Email is selected, Conversation Intelligence enables the shared Gorgias ticket fetch. It does not restrict retrieval to only the selected channel. Eligible tickets from other Gorgias channels are also imported. If you need a channel excluded from ingestion, contact your Heap Customer Success Manager.

With Chat or Email selected, tickets that arrive through SMS, Facebook, Instagram, or Twitter/X are imported and assigned their own channel in Conversation Intelligence, but these channels don't appear in the onboarding wizard and aren't shown in the Conversation Intelligence UI.

Tickets on the Gorgias api, aircall, and tiktok-shop channels are always skipped.

Chat and Email

When Chat or Email is selected, Conversation Intelligence reads eligible Gorgias tickets and their messages. The ticket must have carried the csq_eligible tag for it to be analyzed.

Voice

For a phone ticket, Conversation Intelligence uses the recording from the ticket's call-recording event. It copies the recording into Conversation Intelligence storage, transcribes it, and analyzes the transcript.

A voice ticket without a recording is skipped entirely. If your Gorgias account doesn't attach call recordings to phone tickets, there is nothing for Conversation Intelligence to analyze.

There is nothing to configure inside Gorgias for Voice. Selecting Voice is the only configuration step. Selecting Voice places your program on premium Voice, so confirm that it is in scope before selecting it.

PII redaction is enabled by default for Voice. When Voice is selected, Conversation Intelligence redacts PII from both the stored recording and the transcript. The exception is a program that is deliberately on a no-redaction package.

Ingestion eligibility

Conversation Intelligence analyzes a Gorgias ticket only if it has carried the csq_eligible tag. A ticket that has never carried the tag isn't analyzed, regardless of the channel through which it arrived.

The channel selection in the onboarding wizard determines the available ingestion configuration, but it doesn't override the eligibility tag or the channel-specific rules described above.

Data freshness and history

Freshness

Conversation Intelligence reads your Gorgias account over the REST API. It fetches recently changed tickets roughly once an hour and processes them shortly afterward. A conversation typically appears in Conversation Intelligence within a couple of hours of its last update in Gorgias. Voice uses the same cadence.

History at go-live

At go-live, Conversation Intelligence backfills as far back as the most recent of the following dates:

• The start date agreed during onboarding.
• Your contract signature date.
• Any cut-off date set by the Heap operations team for your account.

The most recent of these dates determines how much history is available. If you need more history than you see, contact your Heap Customer Success Manager. This is a Conversation Intelligence setting, not a Gorgias setting.

Initial backfill volume

The onboarding backfill works backward from go-live until it reaches either the earliest allowed date or a standard target of 40,000 conversations. This target counts conversations across your entire Conversation Intelligence account, including other connected platforms and channels, not Gorgias alone.

Chat and messaging volume counts toward the target first. Email and Voice begin counting after there is no remaining chat history to fetch.

Gorgias rate limits

Conversation Intelligence respects Gorgias rate limits. When Gorgias throttles a request, Conversation Intelligence honors the Retry-after header and retries after the interval specified by Gorgias.

Data privacy and disconnecting

• Eligibility: A conversation is analyzed only if it has carried the csq_eligible tag. Conversation Intelligence stores the raw ticket data for eligible ingestion. An untagged ticket isn't analyzed and doesn't create a conversation.
• Raw data retention: Stored raw ticket data is retained until your account is offboarded, at which point it is deleted. There is no periodic purge.
• Voice recordings: Voice recordings are copied into Conversation Intelligence storage and transcribed. PII redaction covers both the stored recording and the transcript and is enabled by default whenever Voice is selected.
• Customer names: The name on the ticket's customer record is stored only when that setting has been enabled for your account. This setting applies to the customer record only. Sender and recipient details on messages, including names and email addresses, remain part of the stored ticket data.
• Read-only access: Conversation Intelligence never writes to your Gorgias data.

Revoke access

To disconnect the integration, uninstall the Conversation Intelligence app from your Gorgias integration settings. Check Gorgias's documentation for the current navigation path.

Revocation isn't instantaneous. The access token remains valid for the lifetime issued by Gorgias, so reads may continue briefly after you uninstall the app. Also tell your Heap Customer Success Manager that you revoked access. Conversation Intelligence doesn't receive an automatic notification when the grant is revoked, so without that notification it may continue attempting to read from Gorgias and report the connection as failing rather than intentionally withdrawn.

What onboarding validation checks

After access is approved, Conversation Intelligence runs four validation stages against your Gorgias account. The onboarding wizard displays the result of each stage.

Authentication

Conversation Intelligence makes two authenticated reads, one user read and one ticket read, to confirm that approval succeeded and that the credential includes both user and ticket access. A failure at this stage indicates an issue with the credential or authorization, not with the conversation data.

Data shape

Gorgias doesn't provide a schema-description endpoint, so Conversation Intelligence checks real records. It first resolves the csq_eligible tag. A missing tag stops validation and produces the message described in Step 1.

Conversation Intelligence then samples recent tickets and confirms that the required fields are present: spam, customer, tags, and messages on the ticket; the required message fields; and id, email, name, and lastname on the sender. Voice tickets aren't included in this sample.

Trial import

Conversation Intelligence imports a small number of real conversations end to end to verify the complete ingestion path, not only the connection. Voice isn't included in the trial import, so Voice ingestion is confirmed after go-live rather than during validation.

Output check

The final stage reviews the conversations created by the trial import and checks that they contain messages, have agents attributed, and include timestamps and metadata in the expected format.

The output check can report one of the following results:

• Output ok: The sampled conversations passed the check.
• Output ok (with notes): The check passed, with non-blocking observations about the sample. For example, some conversations may have only one participant because an agent hasn't replied yet.
• Output check failed: A sampled conversation has a structural problem after processing. This usually indicates a Conversation Intelligence pipeline or mapping issue rather than a configuration issue in Gorgias.

If a stage can't fetch a recent conversation, there may not have been enough activity in the sampled time window. In that case, the validation can be run again.

Need help?

If you have questions about the required Gorgias access, the csq_eligible tag, supported channels, or the validation results, contact your Heap Customer Success Manager.