Skip to Content
IntegrationsZendeskTroubleshooting

Troubleshooting

This guide covers common issues encountered during setup and operation of the Flexivity AI Zendesk integration. Each issue follows a Symptom, Cause, Fix format.

Marketplace Install Issues

Symptom: Searching for “Flexivity AI” in the Zendesk Marketplace returns no results.

Cause: The app may be a private listing during your evaluation, or you may be searching your installed apps list rather than the marketplace.

Fix:

  1. Confirm you are at the public marketplace (https://www.zendesk.com/marketplace/ ) and not the Currently Installed tab.
  2. If the app still does not appear, contact Flexivity support — your account may need to be added to the private listing while we expand availability.

Install Button Is Grayed Out

Symptom: On the Flexivity AI marketplace listing, the Install button is disabled.

Cause: Your Zendesk user does not have admin permissions, or your Zendesk plan does not allow marketplace apps.

Fix:

  1. Confirm your Zendesk role: Admin Center → Account → Subscription → Account Holder / Admins.
  2. Confirm your Zendesk plan tier: Flexivity AI requires Zendesk Suite Team or higher. See Supported Platforms — Zendesk.
  3. If both are correct and the issue persists, contact Zendesk support — the marketplace install eligibility check is on Zendesk’s side.

OAuth Connect Issues

Zendesk Subdomain Is Already Connected to Another Flexivity Workspace

Symptom: After clicking Allow on the Zendesk OAuth consent screen, you are redirected back to Flexivity with an error message indicating that your Zendesk subdomain is already connected to a different Flexivity organization.

Cause: Zendesk subdomains are unique connection keys in Flexivity. If anyone in your organization previously created a Flexivity instance bound to the same Zendesk subdomain — for example during an earlier trial that was abandoned without disconnecting — the new connection is blocked.

Fix:

  1. Identify which Flexivity workspace owns the prior connection. The error message in the admin console links to a support email; include your Zendesk subdomain in the message.
  2. Either sign in to the prior workspace and disconnect Zendesk, or contact Flexivity support and request a transfer.
  3. Re-run the connect flow.

Symptom: When you initiate the connect flow, the Zendesk OAuth consent screen shows a different Zendesk subdomain than you expected.

Cause: You are signed in to multiple Zendesk accounts in your browser, and Zendesk routed the OAuth request to the wrong session.

Fix:

  1. Sign out of all Zendesk sessions in your browser.
  2. Sign in only to the Zendesk account you want to connect.
  3. Re-run the connect flow.

Alternatively, run the connect flow in an incognito/private browser window to isolate the session.

OAuth Connect Succeeds but No Events Flow

Symptom: The Flexivity admin console shows the Zendesk instance as Active, but opening a test ticket in Zendesk does not produce any AI summary or widget activity.

Cause: Several possible causes, checked in order of likelihood.

Fix:

  1. Wait 15 seconds and refresh the ticket. The first event after connect can take a moment to flow through the pipeline.
  2. Confirm the webhook subscription exists. In Zendesk, navigate to Admin Center → Apps and integrations → Webhooks. You should see a webhook named Flexivity AI Events pointing at https://api.flexivity.ai/v1/zendesk/webhook with status Active.
  3. If the webhook is missing or inactive, the most common cause is that the OAuth grant was canceled before the webhook could be provisioned. Disconnect from the Flexivity admin console (this cleans up partial state) and re-run the connect flow.
  4. Confirm features are enabled. In the Flexivity admin console, open your Zendesk instance’s Features section. Confirm at least AI Summaries is toggled on — see Feature Configuration — Zendesk.
  5. Check for webhook signature failures. In the Flexivity admin console, open the instance dashboard and check the recent jobs view for 401 errors. If you see signature verification failures, the webhook signing secret may be out of sync — disconnect and reconnect to regenerate.

Missing Help Center Module on the Account

Symptom: During connect, the admin console returns an error like “Zendesk Help Center is required but not enabled on this account”.

Cause: Zendesk Help Center is not provisioned on the account. KB Analysis & Authoring requires Help Center; even features that do not strictly require it use the Help Center API surface during connect for validation.

Fix:

  1. In Zendesk, enable Help Center: Admin Center → Help Center → Settings.
  2. Once Help Center is provisioned, re-run the connect flow.

If you do not want to enable Help Center, contact Flexivity support — KB-related features can be disabled per-instance, but the connect-time validation expects Help Center to be reachable.

OAuth Refresh Token Failures

Symptom: After working normally for a period, the Flexivity admin console shows the Zendesk instance with status Reauthorization required. AI features stop running.

Cause: The OAuth refresh token was invalidated. Common causes:

  • A Zendesk admin revoked the OAuth grant from Admin Center → Apps and integrations → Connected apps.
  • The Zendesk user that originally authorized the OAuth flow had their account deactivated.
  • Zendesk has performed a security action on the account that invalidated all outstanding OAuth grants.

Fix:

  1. Open the Flexivity admin console, navigate to the Zendesk instance.
  2. Click Reauthorize Zendesk and follow the connect flow again.
  3. If reauthorization fails repeatedly, check Zendesk’s Connected apps page for the Flexivity AI grant. If it is missing or in an error state, the grant must be re-established from scratch.

Note: Zendesk access tokens are short-lived (~30 minutes in practice). Flexivity refreshes them automatically. You should only see this error if the refresh token itself is invalid — not on routine token expiration.

AI Feature Issues

AI Summaries Not Generating

Symptom: Tickets are created or updated, but no AI summary appears in the Flexivity widget.

Cause: Multiple possible causes, checked in order of likelihood.

Fix:

  1. Check feature is enabled. In the admin console, navigate to your Zendesk instance’s Features section and confirm AI Summaries is toggled on — see Feature Configuration.
  2. Check the instance is connected. The instance status must show Active. If it shows Reauthorization required, follow the OAuth refresh fix above.
  3. Check for processing errors. On the instance Dashboard, check the recent jobs view. If jobs are failing, the error column gives a reason — common causes are 4xx from Zendesk REST (token issue) or 5xx from Bedrock (transient — auto-retries).
  4. Check the webhook is firing. In Zendesk, Admin Center → Apps and integrations → Webhooks → Flexivity AI Events. Click into the webhook and check the recent deliveries. If deliveries show non-2xx response codes from Flexivity, the issue is on Flexivity’s side — contact support.

Recommendations Are Empty or Low Quality

Symptom: The Recommendations section in the Flexivity widget consistently returns no results or suggests irrelevant tickets.

Cause: The knowledge base does not have enough historical Zendesk ticket data, or the historical sync has not been run.

Fix:

  1. Check whether Historical Sync has been completed. In the admin console, navigate to the Features section and check the Historical Sync status.
  2. If the sync has not been run, start one. Recommendations improve significantly with a larger corpus of solved tickets.
  3. If the sync completed but recommendations are still poor, the solved-ticket volume may be too small for meaningful similarity matching. The system works best with at least several hundred solved tickets.
  4. If your historical sync covers only a recent window (e.g., last 30 days), expand the window in Feature Configuration and re-run the sync to backfill more history.

AI Classification Suggestions Are Missing a Topic Value That Exists in Zendesk

Symptom: You added a new dropdown option to your topic ticket field in Zendesk, but Flexivity is not suggesting it as a classification target.

Cause: Flexivity caches the list of available topic values from the Zendesk custom field and refreshes it on a schedule (typically once per 24 hours). New values do not immediately flow through.

Fix:

  1. In the Flexivity admin console, open the Zendesk instance and navigate to Features → AI Classification.
  2. Click Refresh topic values now to force an immediate refresh of the picklist cache from Zendesk.
  3. Verify the new value now appears in the dropdown of available topic values shown in the admin console.

If the new value still does not appear after a refresh, confirm in Zendesk that the dropdown option is enabled (not archived) for the configured field id.

KB Authoring Draft Push Fails with a Permission Error

Symptom: Clicking Push to Help Center on a draft in the Flexivity admin console returns an error indicating the user does not have permission to create a draft article.

Cause: The Zendesk user that authenticated during OAuth connect does not have permission to create draft articles in the target Help Center section.

Fix:

  1. Confirm in Zendesk Help Center → Settings → Permissions that the connected user has the Edit or Publish permission on the target section (Edit is sufficient — Flexivity always writes drafts, never publishes).
  2. If the connected user’s permissions cannot be elevated, disconnect from the Flexivity admin console and re-run the OAuth connect flow signed in as a Zendesk user with the required Help Center permissions.

Widget Issues

Flexivity AI Widget Does Not Appear in the Agent Workspace Sidebar

Symptom: Opening a ticket in Zendesk Agent Workspace does not show the Flexivity AI widget in the sidebar.

Cause: Multiple possible causes.

Fix:

  1. Confirm the Apps sidebar is open. In the Agent Workspace, click the apps icon in the upper-right corner of the ticket view to open the Apps sidebar.
  2. Confirm the marketplace app is installed. In Admin Center → Apps and integrations → Zendesk Support apps → Currently Installed, look for Flexivity AI. If absent, see Marketplace Installation.
  3. Confirm the app is enabled for this agent’s group. Marketplace apps can be restricted to specific groups during install. Check the app’s settings page for group restrictions.

Widget Shows “Not Connected” Banner

Symptom: The Flexivity widget renders in the ticket sidebar but shows a banner reading “Flexivity AI is not connected yet” or similar.

Cause: The OAuth connect flow has not been completed for this Zendesk instance.

Fix: The connect flow is initiated from the Flexivity admin console — there is no Connect button on the Zendesk-side settings page. Go to app.flexivity.ai , open your Zendesk instance, click Connect Zendesk, and follow the Connecting Zendesk procedure.

Widget Shows Errors When Displaying Information

Symptom: The Flexivity widget loads in the ticket sidebar but shows errors when trying to display summaries, recommendations, or other content — for example, “Failed to load,” “Authentication failed,” or a generic error message in place of the expected content.

Cause: The widget authenticates every call it makes to the Flexivity AI cloud (where summaries, recommendations, and feedback data live) using a per-install JWT secret. If that secret has drifted out of sync with what Flexivity expects — for example, after a partial reinstall of the marketplace app, an interrupted OAuth flow that left an old secret in place, or a long period where the install settings were edited externally — the widget’s calls come back as authentication failures and content cannot render.

Fix:

  1. In the Flexivity admin console at app.flexivity.ai , open the Zendesk instance details page.
  2. Click Rotate widget secret (or the equivalent action on the instance details page). Flexivity generates a fresh JWT signing secret and writes it into the marketplace app’s installation settings via the Zendesk Apps API. No action is required on the Zendesk side.
  3. Reload a ticket in Zendesk Agent Workspace. The widget should now load content successfully.

If the errors persist after the rotation, see Getting Additional Help at the bottom of this page — collect a sample of the widget error text and the timestamp before contacting support.

Disconnect and Cleanup

Removing Flexivity AI Completely

To fully disconnect:

  1. Disconnect from Flexivity admin console. This revokes the OAuth grant on Zendesk’s side, removes the webhook subscription, and marks the Flexivity instance as Disconnected.
  2. (Optional) Uninstall the marketplace app. In Zendesk, Admin Center → Apps and integrations → Zendesk Support apps → Currently Installed → Flexivity AI → Uninstall. This removes the agent-facing widget and the configuration screen.
  3. (Optional) Confirm cleanup in Zendesk. In Admin Center → Apps and integrations → Webhooks, confirm the Flexivity AI Events webhook is gone. In Admin Center → Apps and integrations → Connected apps, confirm the Flexivity AI OAuth grant is no longer listed.

After both actions, Flexivity has no access to your Zendesk account and no on-account artifacts remain.

Getting Additional Help

If the issue is not covered here:

  1. Collect the following information:

    • Instance status and recent jobs from the Flexivity admin console dashboard
    • Webhook delivery logs from Zendesk Admin Center → Apps and integrations → Webhooks → Flexivity AI Events → Activity
    • Your Zendesk subdomain and Flexivity instance id
    • A description of what you expected vs. what happened

  2. Contact Flexivity AI support through the administration console’s Help section or email your account representative.

Last updated on
Integration ApproachSecurity