Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Freshdesk to Fondoo

Live4 min readUpdated

Freshdesk in Fondoo: what your AI agent can do with it, what to set up first, the permissions it needs and its limits.

Use a Freshdesk agent API key (Profile settings in your support portal, shown below the change-password section; the agent role decides what the key may do, so pick an agent allowed to view, create, reply to and update tickets) and your helpdesk subdomain, the part before .freshdesk.com. API rate limits are plan-based and every request counts, even invalid ones. Freshdesk webhooks come from Automation rules (Growth plan or higher) and Freshdesk does NOT sign them: Fondoo can only check a shared secret header, so set webhookSecret to a long random token without spaces, add it in the rule as the custom header X-Fondoo-Webhook-Secret, and leave the rule's Requires authentication toggle off.

Official documentation: https://developers.freshdesk.com/api/

Use add_connection_key without fields for a signed, one-use secure paste page. Then call test_connection and inspect confirmed versus unknown permissions. Direct tool credentials carry a chat-log warning. list_connections never returns credentials.

Auth: api_key (HTTP Basic <api key>:X; credential fields subdomain, apiKey (secret), webhookSecret (secret)). Category: support. Required provider scopes: none (the agent role behind the key decides what it may do).

Capabilities are discoverable with list_connector_manifests; invoke them through connector_action. Writes retain shared Fondoo scopes, approvals, dry runs, audit, events and metering. Use rotate_connection_key before expiry and delete_connection to remove stored credentials; revoke upstream credentials separately.

What Fondoo does with Freshdesk

Freshdesk is a helpdesk provider for the M15 support switch: set_provider({siteId, capability:'support', provider:'freshdesk'}) routes the shared support ticket operations to this connection. A Fondoo "ticket" is a Freshdesk ticket and its ID is the numeric ticket ID.

Normalized capabilities (all through connector_action or the support operations):

  • tickets.list (read): without a status, GET /tickets?updated_since=<30 days ago>&order_by=updated_at&order_type=desc (Freshdesk would otherwise return only tickets created in the last 30 days), up to 300 pages; cursor is the page number and limit 1..100. With a status, the Filter Tickets search ("status:<n>") is used: fixed 30 per page, at most 10 pages.
  • tickets.get (read): GET /tickets/{id}?include=requester; description is the plain text version, assignee_id is responder_id.
  • tickets.comments (read): the ticket description as the first customer message (<id>:description), then conversations (GET /tickets/{id}/conversations, 30 per page, at most 10 pages per call with a resume cursor). private conversations are public:false; incoming ones are customer, others agent.
  • tickets.create (write): POST /tickets with status Open (2), priority default normal, optional tags. The comment is HTML-escaped into the description.
  • tickets.update (write): public reply POST /tickets/{id}/reply, private note POST /tickets/{id}/notes with private:true (both HTML-escaped), then one PUT /tickets/{id} for status, priority, tags (replaces the full set) and assignee_id (agent ID, sent as responder_id). Reply and note come first.

Status mapping: Freshdesk 2 → open, 3 → pending, 4 → solved, 5 → closed, 6 and 7 (waiting on customer / third party) → pending, custom statuses → open. Writes: new/open → 2, pending → 3, solved → 4, closed → 5. Priority: 1 low, 2 normal, 3 high, 4 urgent.

Webhooks

Call get_helpdesk_webhook({connectionId}) for the URL (/webhooks/helpdesk/<connectionId>). Freshdesk webhooks come from Automation rules (Growth plan or higher) and are not signed. Fondoo therefore checks a shared secret header: set webhookSecret to a long random token (at least 24 characters from A-Z a-z 0-9 . _ ~ -), add the custom header X-Fondoo-Webhook-Secret with that value in the rule's webhook action, leave "Requires authentication" off, and send a JSON body containing event (ticket_created or ticket_updated) and ticket_id. The secret is compared in constant time. This is weaker than an HMAC: anyone who learns the header value can post events, and there is no replay protection, so treat the secret like a password and rotate it with rotate_connection_key. Only the ticket ID is read; content is re-read through the API.

Human-only topics

Complaints, refunds and legal requests stay human-only: Fondoo classifies new tickets with the site's protected-category rules, raises complaint.opened or refund.requested, alerts a human and requires owner approval for agent replies. This connector has no refund, payment or delete capability.

API endpoints used

Limits and uncertainties

  • Rate limit: per account and plan (a 3,000 calls/hour table on current plans, an older 100/min on Growth); invalid requests and include= embeds consume credits too. Fondoo budgets 15 executes per minute; X-RateLimit-* and Retry-After stay authoritative.
  • Confirmed from the API reference while writing this guide: Filter Tickets returns 30 results per page with page not exceeding 10 and the query URL-encoded in double quotes; List Tickets returns only the last 30 days of created tickets unless updated_since is set, with a 300 page maximum. The reply and note request bodies could not be read in the fetched portion of the reference; the shapes used (body, and private:true for notes) follow Freshdesk's documented examples and should be rechecked.
  • Uncertain: some plans reject include=requester or restrict the Filter Tickets API; the call then fails with a provider error.
  • Uncertain: Freshdesk custom statuses are treated as open.
  • Search results can lag a few minutes behind updates, so a freshly changed ticket can be missing from a status-filtered list.
  • Webhook authenticity relies on a shared secret, not a signature (see above).