Skip to content
threada Docs

Freshworks Marketplace for Freshdesk

This guide defines the Freshworks Marketplace path for Freshdesk as a documented customer-pull follow-on outside the active Zapier-to-ServiceNow public listing wave. It is both a launch-control document and the status page for the generated Freshworks app source now present in the repository; it is not evidence that Freshworks has validated, approved, or published the public listing.

Current Status

Freshworks Marketplace for Freshdesk is planned as a customer-pull public store follow-on. Threada already has a governed Freshdesk action proposal payload for freshdesk_create_ticket in the public API action model, and Studio exposes https://studio.threada.ai/integrations/freshdesk/install to preload the Freshdesk connector preset and runtime integration kind for a pack. A private launch-control package exists at packages/freshworks-marketplace-app for a Freshdesk support_ticket module, current platform v3.0 manifest posture, request-template posture, app settings, listing metadata, setup-guide metadata, reviewer smoke notes, generated Freshworks CLI source, and a packed app ZIP. The public BFF exposes the signed callback route /api/v1/integrations/freshworks/freshdesk/actions/create-ticket, verifies an opaque Threada tenant mapping token from X-Threada-Freshworks-Mapping with FRESHWORKS_MARKETPLACE_MAPPING_TOKEN_SECRET, and forwards only the verified tenant/integration into the runtime FreshdeskCreateTicket action. The Freshworks app stores the opaque mapping token only as a secure app setting that the request template injects into the header; browser JavaScript never reads it. The uploaded source stores no Threada HMAC secret, Secret Manager path, API key, or OAuth secret. Mapping tokens must be signed, expiring fwmap_v1 tokens. Authenticated Threada tenant admins can also install a Freshdesk account API key through POST /api/v1/integrations/freshdesk/directory-install; the BFF stores the credential in Secret Manager and upserts a runtime-bound Freshdesk integration with the freshdesk_create_ticket marketplace action allowlist.

No Freshworks public app, Freshworks Developer Portal public-app listing, Marketplace listing approval, reviewer account evidence, Freshworks CLI validation or pack evidence from the real FDK, or Freshworks review result has been observed in this repository.

Do not submit a public Freshworks Marketplace listing until the chosen Freshdesk app package is built, installable in a reviewer-safe Freshdesk or Freshdesk Omni account, validated end to end, linked to a Public App submission, and supported by reviewer setup evidence.

Do not market or claim Freshworks Marketplace readiness until Freshworks review has accepted the submitted app.

The existing Freshdesk action payload remains tenant-specific governed action work. It should not be described as the public Freshworks Marketplace app.

The enterprise-safe first package should be a narrow Freshworks App for Freshdesk that creates a governed Freshdesk ticket from a Threada WorkItem or customer request. Ticket creation aligns with the live freshdesk_create_ticket action proposal payload and avoids starting with ticket updates, conversations, notes, time entries, customer or company mutations, agent/admin operations, workflow automation, Freshservice scope, or packaged knowledge sync.

Build the first public package as a Freshworks CLI app using the current Freshworks platform path. Freshworks documentation currently makes platform v3.0+ the default for new app development and marks Marketplace Platform v2.3 as deprecated, so the package should use the current module-based manifest model unless Freshworks explicitly directs otherwise during review.

The app should list under Freshdesk for the support-ticket experience and, only if the implementation supports it, Freshdesk Omni. Do not select additional products or modules in the initial version just to broaden listing reach: Freshworks product selection is sticky for future versions, and unsupported module claims create permanent review and maintenance risk.

Positioning

Threada for Freshdesk should help support teams turn governed Threada work into reviewable Freshdesk ticket operations without bypassing policy, approval, idempotency, and audit controls.

The narrow v1 app should stay focused:

  • Install Threada through a Freshworks Marketplace-reviewed Freshdesk app.
  • Start runtime-bound setup from https://studio.threada.ai/integrations/freshdesk/install when a reviewer or customer configures the current Threada connector path before Marketplace app approval.
  • Install a Freshdesk account API key through the authenticated Threada directory credential flow before the Freshworks public app is approved.
  • Bind the Freshdesk account or organization domain to a Threada tenant, pack, queue, or workspace mapping.
  • Create a Freshdesk ticket only from a governed Threada action proposal.
  • Show clear setup-required, approval-pending, succeeded, and failed states in Threada and in the Freshworks app surface where appropriate.
  • Provide public setup/support documentation that explains least-privilege Freshdesk access, request templates, app settings, disconnect, uninstall, and data handling.

The v1 app must not claim that Freshdesk can execute arbitrary third-party actions through Threada. Direct external execution remains inside Threada’s governed Work, Studio, MCP, A2A, or first-party runtime paths.

Source Of Truth

Do not duplicate request or response schemas in this document. Public WorkItem shape and governed action proposal behavior are documented in Threada Public API and its generated OpenAPI artifact at /openapi/public-api.openapi.yaml. The committed source copy is docs/developers/public-api.openapi.yaml.

The generated package at packages/freshworks-marketplace-app is the repository source of truth for the reviewable v1 manifest, request templates, app settings, app source, listing metadata, reviewer smoke notes, and readiness gates. After Freshworks approval, the Developer Portal public-app submission, uploaded package, selected modules, reviewer setup notes, approval result, and any portal-only IDs must be reconciled back into the package inputs and evidence references.

App Surface

Governed Ticket Creation

The first reviewable capability should create a Freshdesk ticket from a Threada WorkItem or customer request. The implementation should use the Freshworks app install path, then let Threada create a governed action proposal that writes to Freshdesk only after the configured policy and approval path permits it.

Inputs should map to the live freshdesk_create_ticket payload fields for subject, description, priority, status, requester_email, requester_name, tags, and custom_fields. Priority, status, tags, requester attribution, and custom fields should be allowlisted or tenant-configured so the public app cannot create noisy, misrouted, or misattributed tickets.

Freshdesk ticket creation requires a requester identifier such as email, requester ID, phone, social ID, or external ID. The public v1 should use requester email only when the Threada workflow has an approved, auditable requester email; otherwise it should return setup-required or approval-required instead of inventing requester identity.

Server-side or proxied calls from the Freshworks app must use Freshworks request templates, app settings, OAuth, or other Freshworks-supported secure mechanisms so secrets are not exposed in browser JavaScript. If Threada performs the Freshdesk write server-side, the Freshworks app should call Threada through an authenticated, tenant-bound endpoint and let Threada own Secret Manager storage, policy checks, idempotency, and audit. Secret Manager resource names are operator metadata only; do not place them in Freshworks request-template headers, front-end code, screenshots, or marketplace upload bundles.

Outputs must give the Threada user a clear success, setup-required, approval-pending, or failed state and preserve the Freshdesk ticket reference when one is returned. Do not return only a generic success message; reviewers need to see the install-to-action-to-ticket journey.

Conversation And Update Follow-On

Threada does not currently expose a public Freshdesk ticket-update or conversation action payload. A Freshworks Marketplace listing can reference comment, note, reply, update, time-entry, or ticket-field capability only after the corresponding governed payload, request template or server-side endpoint, field allowlists, visibility controls, idempotency, audit behavior, reviewer flow, and Freshworks review evidence exist.

The app must make requester-facing versus internal-note behavior explicit before any conversation-writing capability is marketed.

Setup And Tenant Mapping

The app must bind an installed Freshdesk account, organization domain, or current-host account URL to a Threada tenant, pack, queue, or workspace mapping before claiming production readiness. If setup is incomplete, Threada should show a clear setup-required response instead of silently dropping the request or attempting an unauthenticated Freshdesk write.

The current Threada-side credential install path is POST /api/v1/integrations/freshdesk/directory-install. Submit resource_key as the Freshdesk account domain, for example acme.freshdesk.com; submit endpoint_url as the matching account origin, for example https://acme.freshdesk.com; and submit credential.api_key (aliases: freshdesk_api_key or token). The endpoint host must match freshdesk_account_domain and must target a Freshdesk account host. The BFF writes a freshdesk_api_key_v1 payload to Secret Manager, then upserts a tenant-scoped INTEGRATION_TYPE_FRESHDESK integration with freshdesk_create_ticket as both the capability set and marketplace action allowlist. The console-shell runtime client exposes this as installMarketplaceDirectoryCredential.

Reviewer setup notes must include the exact Freshdesk or Freshdesk Omni test account, test agent or admin, Threada tenant, test pack or queue, install URL or Marketplace preview URL, expected ticket fields, and cleanup instructions. Credentials, tokens, cookies, raw ticket exports, requester PII, and customer data must stay out of repo evidence and screenshots.

Marketplace Package Requirements

Freshworks documentation routes public Freshworks apps through the Freshworks Developer account and Public App tab, a Freshworks CLI app package, an uploaded packed ZIP, module/product selection, app information, media and installation details, support details, privacy and security questionnaire, app settings where applicable, and Freshworks approval.

Required package work before submission:

  • Create a Freshworks Developer account and Public App entry for a Freshworks App. Do not use Custom App as the public Marketplace path because custom apps are private to a customer account and not subject to the same Marketplace review posture.
  • Build the app with the current Freshworks CLI and current platform defaults. If Freshworks requires a specific module path, document that module decision and keep it aligned with the packed manifest.
  • Register at least one non-common Freshworks module in the manifest. For the v1 ticket workflow, start with the Freshdesk support-ticket module and add only the common module or Freshdesk Omni support where the implementation is actually tested.
  • Select the Freshdesk product listing in the Developer Portal based on the modules identified from the uploaded package. Treat selected products as sticky for future app versions.
  • Add a reviewable app UI surface or setup surface that can show install/setup state, mapping state, and ticket-action status. Use Freshworks-supported placeholders for the chosen module.
  • Add manifest.json, module locations or events, secure app settings in config/iparams.json, request templates in config/requests.json where the app calls Threada or Freshdesk, and any serverless or front-end code needed for the install and action flow.
  • Use Freshworks request method, OAuth support, app settings, or a Threada-owned server-side API so API keys, tokens, and client secrets are not exposed in front-end app code. Production request templates must use HTTPS, call the expected Freshdesk action route, and leave Threada signing secrets in Threada server-side infrastructure.
  • Store only the opaque Threada tenant mapping token in a secure Freshworks app setting and inject it through the request template header X-Threada-Freshworks-Mapping. The mapping-token verifier secret is a Threada Secret Manager value mounted into the public BFF as FRESHWORKS_MARKETPLACE_MAPPING_TOKEN_SECRET. The token must be signed and expiring; non-expiring mapping tokens are rejected by the BFF.
  • Implement install, settings validation, disconnect or uninstall cleanup, authorization failure handling, and tenant/account mapping.
  • Implement governed ticket-creation proposal, execution, idempotency, audit trail, setup-required state, approval-pending state, and failure handling.
  • Add allowlists for priority, status, tags, requester attribution, and custom fields before exposing them in public copy.
  • Validate locally with fdk run in Chrome and a reviewer-safe Freshdesk account, then run fdk validate and fdk pack. Freshworks expects code coverage for Marketplace publication; plan for the documented 80 percent coverage posture before submission.
  • Upload the packed ZIP to the Freshworks Developer Portal Public App flow and verify that the identified modules and selected product are correct.
  • Prepare Marketplace app information: app name, overview, short description under the 100-character limit, categories, and subcategories. If public copy describes AI behavior, select the AI category and answer AI/GenAI questions transparently.
  • Prepare media and support details: transparent PNG icon at 400 x 400 or greater, module-specific screenshots at 1600 x 1000 or greater, public YouTube or Vimeo video link, installation instructions, support email, support URL, alternate review email, privacy URL, and terms URL.
  • Complete privacy and security questionnaire with countries of processing, third-party domains, encryption posture, logging/export behavior, EEA transfer mechanism, uninstall deletion behavior, retention periods, OWASP posture, and custom-retention support where applicable.
  • Prepare public setup/support, privacy, terms, security/data-handling, and data-deletion documentation.
  • Prepare reviewer setup notes, test account access, expected ticket output, cleanup instructions, and sanitized screenshots.
  • Submit only after the packaged app is installable, testable, and aligned with the listing content. Wait for Freshworks approval before public-readiness claims.

Explicit Non-Goals

  • No public Freshworks Marketplace claim until a first-class Freshworks App for Freshdesk exists and Freshworks review passes.
  • No Custom App upload, private install link, manually provisioned API key, or tenant secret as the public Marketplace install path.
  • No unmanaged direct Freshdesk writes from the Marketplace app.
  • No broad ticket, contact, company, agent, admin, workflow, account, export, or Freshservice/Freshsales/Freshchat scopes unless the exact v1 capability requires them and the implementation is validated end to end.
  • No Freshdesk update, conversation, public reply, private note, time-entry, watcher, association, deletion, restore, or bulk operation claim until an authenticated, tenant-scoped, auditable path exists and is reviewed.
  • No packaged Freshdesk knowledge sync claim until an authenticated, tenant-scoped, auditable sync path exists and is reviewed.
  • No customer-data screenshots, raw ticket exports, requester lists, OAuth tokens, API keys, cookies, or private tenant payloads in Marketplace screenshots or review evidence.
  • No positioning as a generic “AI agent executes any Freshdesk action” app. Public copy must stay anchored to governed ticket work, setup, and review.

Review Gates

Implemented:

  • Public API action types include freshdesk_create_ticket.
  • Public BFF mapping code converts Freshdesk create-ticket payloads into governed action requests and proposal views.
  • Authenticated Threada tenant admins can install Freshdesk account API-key credentials through /api/v1/integrations/freshdesk/directory-install, which writes to Secret Manager and upserts a runtime-bound Freshdesk integration with the freshdesk_create_ticket allowlist.
  • Public API docs and generated OpenAPI are published.
  • Private Freshworks Marketplace launch-control package exists at packages/freshworks-marketplace-app.
  • Studio exposes the public setup handoff at https://studio.threada.ai/integrations/freshdesk/install, which preloads the Freshdesk runtime integration kind and connector preset before the customer or reviewer supplies the tenant-specific Freshdesk endpoint and Secret Manager reference.
  • The package selects the v1 Freshdesk support_ticket module with common, renders manifest and request-template views, documents app settings, field allowlists, reviewer smoke flow, listing metadata, setup/support metadata, server-side signing posture, and fail-closed readiness evidence.
  • Generated Freshworks CLI source exists under the package build output, including manifest.json, config/requests.json, config/iparams.json, the ticket sidebar app, install/uninstall server handler, icon, and threada-freshworks-app.zip.
  • Public BFF callback /api/v1/integrations/freshworks/freshdesk/actions/create-ticket verifies the secure-header opaque mapping token with FRESHWORKS_MARKETPLACE_MAPPING_TOKEN_SECRET, derives an idempotent runtime intake ID, and dispatches a tenant-bound FreshdeskCreateTicket action.
  • Package validation passes for the current launch-control config, while submission validation remains blocked until real production values, structured evidence references, Freshworks CLI validation/pack evidence, and Freshworks review evidence exist.

Missing:

  • Freshworks Developer account, Public App entry, app listing, product selection, categories, support/privacy/terms URLs, listing content, and reviewer setup path.
  • Real Freshworks CLI fdk run, fdk validate, and fdk pack evidence against a reviewer-safe Freshdesk account and the generated source.
  • Freshworks Developer Portal upload, portal-side module/product confirmation, review submission, approval tracking, and review result.
  • Operator UI or admin workflow that mints the opaque tenant mapping token for the correct Freshdesk account and shows setup-required, approval-pending, success, failure, disconnect, and uninstall states to reviewers.
  • Tenant-specific ticket field allowlists and safe requester-attribution configuration beyond the package-level field envelope.
  • Public setup/support docs, data disclosure, privacy/terms/security links, screenshots, video, test instructions, setup notes, reviewer access, expected ticket output, and cleanup instructions.
  • Code coverage posture, sanitized screenshots, reviewer account evidence, and approval report before public-readiness claims.

Blocked:

  • Public submission is blocked until the generated first-class Freshworks App package is validated with the real FDK, installed in a reviewer-safe account, linked to a Developer Portal Public App, and supported by sanitized evidence.
  • Public-readiness claims are blocked until Freshworks review approves the app.
  • Update, conversation, note, time-entry, contact/company, agent/admin, and packaged knowledge-sync claims are blocked until corresponding governed payloads, Freshworks app surfaces, API implementations, tests, and review evidence exist.

Next Actions

  1. Create or connect the real Freshworks Developer account and Public App entry, then fill the scaffold environment values from that source of truth.
  2. Run the generated Freshworks CLI source with fdk run, validate with fdk validate, pack with fdk pack, and compare the generated ZIP with the FDK output.
  3. Implement the operator/admin mapping-token minting workflow and reviewer setup states around the existing signed BFF callback.
  4. Build public setup/support, privacy, terms, security, and deletion docs.
  5. Prepare listing copy, screenshots, video, reviewer setup notes, and cleanup instructions.
  6. Run fdk validate, fdk pack, reviewer-safe install tests, and Freshworks Developer Portal submission after implementation evidence is ready.