Connect Zendesk to Conversational Intelligence

Overview

Use this guide to connect Heap Conversation Intelligence to your Zendesk account through OAuth 2.0.

After the connection is complete, Conversation Intelligence reads selected Zendesk data to ingest and analyze supported conversations. This includes:

• Support tickets: Conversations created through email, web forms, APIs, and Agent Workspace native messaging.
• User data: Agent and administrator information associated with each conversation, retrieved from the Zendesk Users resource.

Conversation Intelligence requests read-only access for core analytics. It doesn't create, edit, or delete data in your Zendesk account.

To learn more about setting up Conversational Intelligence, see Getting started: Conversational Intelligence.

Permissions

The credential used by Conversation Intelligence must be able to read the conversations you want analyzed for every agent whose work you want scored. In Zendesk, the credential must belong to, or be approved by, a staff user with the required role.

Email and ticket channels

The integration user must be an Agent or Administrator. End users can't call these APIs. The user's role must grant the following access:

• Read access to all relevant tickets. The user must be able to access all relevant tickets across the account, not only tickets assigned to that user. A standard Administrator or a custom agent role with Access: All tickets satisfies this requirement. A role limited to tickets in the user's groups can exclude conversations from other groups.
• Read access to users. Conversation Intelligence uses the agent and administrator roster to attribute messages to agents and resolve names and email addresses. Without this access, agent-email-based ingestion filtering doesn't work.
• Read access to ticket audits and history. This is a separate permission layer. Messaging transcripts, status changes, and side conversations are rebuilt from /tickets/{id}/audits. A credential that can read tickets but not audits fails during ingestion.

These are separate permission layers in Zendesk. A valid token, confirmed by a successful GET /users/me request, doesn't guarantee access to users, tickets, or audits. Conversation Intelligence validates each layer independently during onboarding.

Set up the connection

Step 1: Locate your Zendesk base URL

Your Zendesk base URL follows this format: https://<your-subdomain>.zendesk.com.

1. Sign in to your Zendesk account.
2. Look at the URL in your browser's address bar.
3. Copy your base URL. For example: https://acme-corp.zendesk.com.
    

Step 2: Create an OAuth client in Zendesk

1. Sign in to Zendesk as an Administrator.
2. Go to Admin Center, or Settings, then select Apps and integrations and OAuth clients. Depending on your Zendesk version, this may appear under Zendesk API and OAuth Clients.
3. Click Add OAuth client.
4. Complete the form:
   • Name: Enter a clear name, such as CSQ CI Integration.
   • Description: Enter an optional description.
   • Company: Enter your company name.
   • Identifier: Enter a unique value, such as csq_ci_integration. Save this value as your Client Identifier.
   • Client kind: Select Confidential.
   • Redirect URL: Add https://live.loris.ai/zendesk/callback.
5. Click Save.
6. Copy the secret immediately. Zendesk displays the secret after you save the client and only displays it once. Store it securely as your Client Secret.
    

Step 3: Connect Zendesk in the Conversation Intelligence onboarding wizard

1. Open the Conversation Intelligence onboarding wizard.
2. Select Zendesk from the list of integration providers.
3. Enter the values requested by the wizard, including your Zendesk base URL, Client Secret, and API key or Client Identifier.
4. After tagging the conversations you want to ingest, select I've added the Heap tag and I'm ready to connect.
5. Click Connect platform and sign in to Zendesk to complete the OAuth 2.0 flow.

After authentication is complete, Conversation Intelligence can securely access the approved Zendesk data required for ingestion and analysis.

Supported channels

Zendesk Messaging and Zendesk Chat are different Zendesk products. Confirm which product and channel your organization uses before selecting channels in the onboarding wizard.

Ticket-based channels

Conversation Intelligence ingests the following channels through Zendesk's Support Tickets API. Each conversation is represented as a Zendesk ticket.

Ingestion scope and eligibility

Conversation Intelligence applies the following rules to ticket-based channels.

Terminal-state filter

Conversation Intelligence ingests only conversations in the Solved or Closed state. Tickets in new, open, pending, or hold aren't ingested.

CSQ eligible filter

When eligibility filtering is enabled, Conversation Intelligence adds the csq_eligible tag to the Zendesk search export query. Only tickets with this tag are eligible for ingestion.

Exclusions

• Answer Bot tickets: Tickets with via.channel == 'answer_bot_for_web_widget' are skipped.
• Unsupported channels: Tickets with a via.channel value that isn't in the supported channel mapping are skipped. For example, chat_transcript from another source isn't supported.
• Zendesk Messaging without a customer reply: Single-message Messaging tickets where the only message isn't from the end user are skipped.
• Voice without a recording: Tickets without a VoiceComment are skipped. Voicemails and calls without a recording URL may be partially skipped.

API access

API requests

Conversation Intelligence uses GET requests to read data for ingestion. It doesn't use write requests.

The following endpoints are used for email and ticket channels: https://<subdomain>.zendesk.com/api/v2/...

Fields Conversation Intelligence reads

Conversation Intelligence reads the fields listed below. If an optional field isn't available in your Zendesk account, it is ignored. Ingestion is read-only.

Ticket

• id, the ticket ID
• via.channel, the origin channel, such as email, web, API, native messaging, voice, or chat
• via.source.from and via.source.to, customer name when PII storage is enabled
• status, the ticket status
• created_at, the creation time
• updated_at, the last update time used for incremental discovery
• tags, the ticket tags, including csq_eligible when eligibility filtering is enabled

Ticket comment

• id
• author_id
• created_at or created
• plain_body, body, or html_body
• public
• type, such as VoiceComment
• attachments
• via.channel and via.source

Ticket audit

• created_at
• author_id
• events[], including type, field_name, value, previous_value, macro_id, and thread_id
• value.history[] for messaging, including actor_id, actor_type, actor_name, message, timestamp, message_id, and type

Ticket metrics

• reply_time_in_seconds.calendar, first reply time
• first_resolution_time_in_minutes.calendar, handle time

Side conversation events

• id
• created_at
• message.subject
• message.html_body
• message.from and message.to
• side_conversation_id

Enrichment metadata

• Group: id, name
• Ticket field: id, title, active, custom_field_options[]
• Ticket form: id, name
• Brand: id, name
• Macro: id, actions[]

Voice, when enabled

• call_id
• recording_url
• recording_type, excluding voicemail
• started_at
• call_duration
• answered_by_id and answered_by_name
• via.source

Legacy Chat data

Legacy Zendesk Chat isn't supported. The following fields may appear on a related ticket or in source data but aren't used to ingest a standalone Chat transcript:

• id
• zendesk_ticket_id
• history[], including type, timestamp, index, msg, sender_type, agent_id, and name
• rating, response_time, duration, tags, visitor.name, and hashed visitor.id

User

• id
• name
• email
• role, where only agents and administrators are treated as agents
• Optional user_fields.cs_agent_level

Need help?

If you have questions about the required Zendesk permissions, OAuth setup, or supported channels, contact your Heap Customer Success Manager.