Support tools — Zendesk, Intercom, and Freshdesk
Connect Zendesk, Intercom, or Freshdesk. Zendesk and Intercom connect via OAuth; Freshdesk connects with an API key. This guide walks you through each.
Support tools — Zendesk, Intercom, and Freshdesk
Zendesk, Intercom, and Freshdesk are the inbound support providers Watari supports today. All three encrypt credentials at rest and can be disconnected without losing historical bug data.
What the integrations share
- Encrypted credentials. Tokens (Zendesk/Intercom) and the API key (Freshdesk) are AES-256-GCM encrypted before they are written to the database. They are never logged.
- Verified webhooks. Zendesk and Intercom webhooks are verified against the provider's HMAC signature. Freshdesk has no signed-webhook product, so its inbound webhook is authenticated with a per-tenant secret token you place in a request header (constant-time compared). In every case the ticket is re-fetched from the provider before processing — the webhook body is never trusted for content. Duplicate events are deduplicated by event ID.
- Disconnect without data loss. Disconnecting a support tool stops new tickets from flowing in, but all existing bugs, mappings, and RCAs remain in your Watari workspace.
How they connect differs by provider:
- Zendesk & Intercom use OAuth — one click, a consent screen, and Watari registers its own webhook automatically.
- Freshdesk uses an API key (Freshdesk offers no OAuth for external apps), and you create one Automation Rule that fires when your team escalates a ticket — by assigning it to an Engineering group (or setting the Type) — so only escalated tickets reach Watari. Watari gives you the exact URL, header, and body to paste — about 90 seconds.
If your organization has multiple Zendesk instances (for example, one for customer support and one for internal IT), only one instance connects per Watari workspace. Use separate Watari workspaces — one per Zendesk subdomain — to route them independently.
Connect your support tool
Connecting Zendesk
In the Watari dashboard, go to Settings → Integrations and click Connect Zendesk.
Enter your Zendesk subdomain. This is the part before .zendesk.com — for example, if your support portal is at acme.zendesk.com, enter acme.
You are redirected to the Zendesk OAuth authorization screen. Sign in with an account that has admin permissions on the Zendesk instance, then click Allow.
You are returned to Watari. The connection status shows as Connected and a webhook is registered on your Zendesk account automatically.
What Watari reads from Zendesk
Ticket subject, body, public comments, internal comments, status, priority, tags, custom fields, requester display name and email, and attachments (including screenshots). Watari reads only the tickets that reach it via webhook — you control that scope with a tag-based trigger if you prefer (for example, fire only when a needs-engineering tag is applied).
What Watari writes back to Zendesk
A single public comment posted to the ticket after the fix ships to production — the customer-facing RCA. Optionally, an internal note linking to the draft PR.
What gets extracted
Ticket content goes through structured extraction: severity, repro steps, expected vs. actual behavior, customer impact, and the customer's original words. Non-bug tickets (billing questions, account access, feature requests) are classified and skipped — they never produce a Mapped Bug.
Connecting Intercom
In the Watari dashboard, go to Settings → Integrations and click Connect Intercom.
You are redirected to the Intercom OAuth authorization screen. Sign in with a workspace admin account and click Authorize access.
Select the Intercom workspace you want to connect if prompted (relevant for accounts with multiple workspaces).
You are returned to Watari. The connection status shows as Connected and Watari subscribes to conversation events on your workspace.
What Watari reads from Intercom
Conversation parts (both customer and teammate messages), conversation attributes (state, tags, custom attributes, team assignment), contact display name and email, and attachments including screenshots. You can scope which conversations reach Watari by Intercom team assignment — only conversations assigned to the configured team trigger extraction.
What Watari writes back to Intercom
A single reply posted to the original conversation after the fix ships to production — the customer-facing RCA. Intercom's API deduplication ensures retries never double-post.
What gets extracted
Same structured extraction as Zendesk: severity, repro steps, expected vs. actual behavior, customer impact, and the customer's original words. Conversations that do not contain a reportable bug — billing disputes, onboarding questions, feature requests — are classified and skipped.
Connecting Freshdesk
Freshdesk has no OAuth for external apps, so you connect with an API key and forward tickets with one Automation Rule. It's still self-serve — a short form instead of a redirect.
In Freshdesk, open your profile → Profile Settings → View API Key. Use a dedicated admin agent so the key keeps ticket read and reply access even if staff change. If the API key shows as disabled, enable it first: Admin → Agents → (your agent) → API Key access → toggle it on → Update, then reopen Profile Settings and copy the key.
In the Watari dashboard, go to Settings → Integrations and click Connect Freshdesk. Enter your Freshdesk domain (the part before .freshdesk.com) and paste the API key. Watari validates the key against Freshdesk before saving it, AES-256-GCM encrypted.
Watari shows you a webhook URL and a secret token. You now create one automation rule so Watari only receives the tickets your team explicitly escalates — not every ticket. Freshdesk has no "tag added" automation trigger, so escalation is a ticket property change an agent makes after triage.
Recommended — assign to a group. In Freshdesk, go to Admin → Workflows → Automations → Ticket Updates and create a rule:
- Event: Agent or Group is updated (property changed → Group)
- Condition: Group is your Engineering group
- Action: Trigger Webhook → POST to the webhook URL. Tick Add custom headers and enter the secret as JSON —
{"X-Watari-Token": "your-secret"}(no stray spaces, or the webhook silently won’t fire). For the body, switch Content from Simple to Advanced and paste the JSON body Watari shows you.
One-time: create a group like Engineering (Admin → Team → Groups) if you don't already have one. Agents then escalate by moving a ticket into that group — the same gesture as assigning to a team in Intercom.
No-setup alternative — Ticket Type. Same rule, but Event: Ticket property changed → Type and Condition: Type is Bug (or the built-in Incident). Agents escalate with the Type dropdown, no group to create.
Don't build the condition on a tag if your Freshdesk is new. Freshdesk's tag picker only offers tags that already exist, so on a fresh account the condition looks broken. Group, Type, and Priority always have values to choose from.
Save the rule. When an agent escalates a ticket (moves it to the Engineering group, or sets the Type), it flows into Watari. Copy the secret when it's shown — it isn't displayed again; to rotate it, disconnect and reconnect (then update the URL and header in your rule, or Freshdesk keeps posting to the old ones).
Two Freshdesk quirks that silently break the rule.
- Fill the custom-header box before you save. If Add custom headers is ticked but the box is still empty when you hit Save, Freshdesk saves the toggle back off. The rule looks configured, sends no token, and every ticket is rejected — the exact shape of "Watari isn't receiving my tickets."
- Switch Content from Simple to Advanced. The JSON body Watari gives you can only be sent in Advanced mode. Leave it on Simple and Freshdesk sends its own payload shape instead.
Freshdesk automations and webhooks require the Growth plan or higher — the Trigger Webhook action does not exist on Free, so downgrading is never a fix. The custom-header value must have no stray spaces or the webhook silently won't fire. If saving the rule fails with Freshdesk's generic "Please check rule configurations", check the rule name first — a duplicate name produces that same message. If a ticket doesn't appear in Watari, confirm the rule matched (right group/type) and the header is exact.
What Watari reads from Freshdesk
Ticket subject, description, public replies and private notes, status, priority, tags, requester display name and email, the requester's company, and attachments (including screenshots). Watari re-fetches the full ticket from Freshdesk's API for every forwarded ticket, so it always reads the current state rather than the webhook payload.
What Watari writes back to Freshdesk
A single public reply posted to the ticket after the fix ships to production — the customer-facing RCA. Optionally, a private note instead.
What gets extracted
Same structured extraction as Zendesk and Intercom: severity, repro steps, expected vs. actual behavior, customer impact, and the customer's original words. Non-bug tickets are classified and skipped — they never produce a Mapped Bug.
OAuth errors and reconnection
If the OAuth flow fails partway through (network timeout, user cancels authorization, session expires), go back to Settings → Integrations and start the connection flow again. OAuth state is short-lived; a fresh flow is the correct fix.
If the integration shows a Connection error status after being connected, it means Watari received a webhook but the token exchange failed or was revoked. Disconnect and reconnect from Settings → Integrations to re-authorize.
Next: Install the Watari GitHub App and configure CODEOWNERS-driven PR routing — install the GitHub App, select repositories, and configure CODEOWNERS-driven PR routing.