Skip to content
threada Docs

Zendesk setup and support

Threada for Zendesk turns governed Threada work into reviewable Zendesk ticket operations. The current runtime path is intentionally narrow: it supports a global-OAuth install for one Zendesk subdomain, tenant-scoped credential storage, and governed create-ticket execution from Threada. It does not perform unmanaged Zendesk writes, run macros, bulk-update tickets, merge tickets, mutate users or organizations, sync Help Center content, or act as an autonomous AI ticketing agent.

This guide supports private Zendesk reviewer testing once a Marketplace review package is available and public Zendesk users after Zendesk approves and lists the app or integration. Until the Zendesk Marketplace app is approved, the OAuth-backed Zendesk integration remains tenant-specific integration work and should not be treated as the public Zendesk Marketplace app.

Requirements

Before installing or testing the Zendesk integration, make sure you have:

  • An active Threada tenant.
  • Studio or Admin access for the Threada workspace that should create Zendesk tickets.
  • A Zendesk Support account or Zendesk-sponsored test account prepared for reviewer testing.
  • Permission to authorize the public Threada global OAuth client for the target Zendesk subdomain.
  • The Zendesk subdomain entered in Threada Studio during OAuth install.
  • For private reviewer testing, the exact Marketplace preview URL, test subdomain, reviewer user, setup notes, expected ticket fields, and cleanup instructions provided through the approved Zendesk review channel.

Do not use production customer Zendesk accounts, customer tickets, raw exports, requester lists, OAuth tokens, cookies, or screenshots containing private tenant data for Marketplace review evidence.

Discover or install the integration

After Zendesk approves the public listing, open Threada from Zendesk Marketplace. During private review, use only the Marketplace preview or reviewer path provided in the approved review notes.

The Threada-side public install handoff is https://studio.threada.ai/integrations/zendesk/install. To start Zendesk OAuth directly from public setup or reviewer notes, append the Zendesk subdomain, for example https://studio.threada.ai/integrations/zendesk/install?subdomain=acme. When no subdomain is supplied, Studio routes the user to the connector setup panel so the Zendesk subdomain can be entered before authorization.

  1. Open the Zendesk Marketplace listing or approved preview link for Threada.
  2. Review the data disclosure, privacy, terms, and support links.
  3. Start the connection flow from the listing, Threada setup link, or Studio connector readiness panel.
  4. Authorize the Threada global OAuth client for the Zendesk subdomain prepared for review.
  5. Confirm Threada shows the Zendesk account as connected.

If the authorization flow fails, stop and fix the Marketplace listing, global OAuth client, redirect URL, OAuth state validation, production URL, or reviewer test-account setup before continuing.

Connect Zendesk to Threada

The Zendesk integration must be mapped to a Threada tenant and receiving workspace before approved proposals can create tickets.

  1. Sign in to Threada Studio with an admin or builder account.
  2. Open the workspace or pack that should create Zendesk tickets.
  3. Open the connector readiness panel for Zendesk.
  4. Enter the Zendesk endpoint or subdomain, authorize the Threada global OAuth client, then bind the authorized Zendesk integration to the Threada workspace or pack.
  5. Select the receiving queue, approval policy, and ticket field allowlist.
  6. Save the mapping and run the connection test if one is available.

If the reviewed build does not yet expose a self-service Studio mapping UI, follow the reviewer setup notes for the exact Zendesk test subdomain, Threada workspace, queue, allowlisted ticket fields, and cleanup steps prepared for review. Do not infer tenant mappings from subdomain names, requester emails, or ticket titles alone.

Create a governed Zendesk ticket

Create a Zendesk ticket only through a governed Threada action proposal.

  1. Open or create the prepared Threada WorkItem.
  2. Create a Zendesk ticket proposal using the reviewed workflow.
  3. Confirm the proposal shows the subject, description, requester, priority, tags, and other allowlisted fields that will be sent to Zendesk.
  4. Approve the proposal when the configured policy allows it.
  5. Confirm Threada shows a succeeded state and records the Zendesk ticket reference.
  6. Open the ticket in Zendesk and confirm the fields match the approved proposal.

Ticket updates and comments are follow-on capabilities. They must not be marketed until the public app proves the required OAuth posture, Marketplace request headers, field allowlists, public/private comment behavior, idempotency, audit behavior, reviewer flow, and Zendesk review evidence.

Setup-required responses

If the integration is authorized but not connected to a Threada tenant or workspace, Threada should show a setup-required response instead of silently dropping the request or attempting an unauthenticated Zendesk write.

Common setup issues:

  • The Zendesk subdomain or account is not mapped in Threada.
  • The mapped Threada workspace or pack was disabled.
  • The receiving queue or approval policy is missing.
  • Required ticket field allowlists are incomplete.
  • The Marketplace package still uses placeholder listing, OAuth, support, privacy, terms, test-subdomain, organization, or app identifiers.
  • The app points to a development, staging, sandbox, ngrok, or otherwise non-production URL.
  • Marketplace request headers are missing from external Zendesk API calls after Zendesk assigns the Marketplace organization and app identifiers.
  • OAuth state validation or token exchange failed, the stored refresh token was revoked or rejected and requires reconnect, or the public revocation and disconnect flow has not yet been approved.

For review builds, include the Zendesk test subdomain, Threada workspace, proposal ID, approximate test time, and sanitized error text in support requests. Do not send OAuth client secrets, access tokens, cookies, raw Zendesk ticket exports, requester PII, or private ticket content.

Disconnect or uninstall

To stop creating Zendesk tickets:

  1. In Threada Studio, disable or remove the Zendesk mapping for the workspace, pack, subdomain, or account.
  2. Revoke the Zendesk OAuth authorization if the account should no longer be connected.
  3. Run the reviewed test workflow and confirm Threada returns setup-required feedback rather than creating a new ticket.

Disconnecting the integration stops future Zendesk ticket creation. Existing WorkItems, proposals, approvals, Zendesk ticket references, and audit events remain available in Threada according to the tenant retention policy.

Data handling

For v1, Threada stores the Zendesk subdomain or account mapping, OAuth authorization metadata, ticket identifiers returned by Zendesk, and the ticket fields required for approved ticket creation. Threada uses this data only to create governed Zendesk tickets, show setup and execution status, support disconnect, and maintain an auditable record.

The public install path must use Zendesk global OAuth for multi-customer server-side Zendesk API access. Do not use customer API tokens, regular OAuth tokens, or manually provisioned tenant secrets as the public Marketplace install path. External Zendesk API requests must include Zendesk Marketplace request headers after Zendesk assigns the Marketplace identifiers.

If a future version adds ticket updates, comments, macros, user or organization mutation, Help Center sync, Sell, Chat, messaging, or broader ticket access, Threada must update this guide, explain the exact data use, complete the required security and privacy review, and submit the updated app or integration for Zendesk review before marketing the new capability.

Support

For setup help, contact support@threada.ai. For privacy or deletion requests, contact privacy@threada.ai. To report a security issue, contact security@threada.ai.

Support requests for the Zendesk integration receive a response within 2 business days. Include the Threada tenant, Zendesk subdomain, proposal or ticket reference when available, app version when known, approximate test time, and sanitized error text. Do not send secrets, tokens, cookies, raw ticket exports, requester lists, customer exports, or private ticket content.