> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Gorgias troubleshooting

> Debug Gorgias connection, webhook, AI reply, and handoff issues — 401 credential failures, silent ticket sync, duplicates, escalations that never fire.

Before debugging, have this ready:

* Your Gorgias <Tooltip tip="The Base64-encoded API key from Gorgias Settings → REST API.">API key</Tooltip> and <Tooltip tip="The subdomain of your Gorgias helpdesk URL (e.g. 'acme' from acme.gorgias.com).">domain prefix</Tooltip>.
* A specific <Tooltip tip="OpenCX's identifier for a single conversation thread. Visible in the Inbox URL.">session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Gorgias ticket ID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias.

<Tip>
  Re-enter and click **Test & Save** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** find the session in your [OpenCX Inbox](https://platform.open.cx/inbox) and check the AI reasoning, tool calls, and handoff event. That is faster than inspecting webhooks or logs.
</Info>

## Common scenarios

Jump to the symptom that matches what you are seeing.

### **"Failed to save" or credentials rejected on save**

<Tooltip tip="Usually caused by a revoked API key, a wrong domain prefix, or a Gorgias plan without API access.">Likely cause</Tooltip>: API key revoked, domain prefix wrong, or Gorgias plan does not include REST API access.

**Fix:** regenerate the API key in Gorgias under **Settings → REST API**. Confirm the domain prefix matches your Gorgias helpdesk URL (e.g. `acme` from `acme.gorgias.com`). Confirm your Gorgias plan includes API access.

### **Webhook not receiving events**

<Tooltip tip="The webhook URL was not added to Gorgias, or the subscribed event types are wrong. Without the webhook, OpenCX receives no ticket messages.">Likely cause</Tooltip>: webhook URL not configured in Gorgias, wrong event subscriptions, or the webhook URL was changed after a credential update.

**Fix:** open your Gorgias webhook settings and confirm the URL matches the one shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias. Confirm the webhook is subscribed to **ticket message created** events. If you recently re-saved credentials, the webhook URL may have changed — copy the new one.

### **AI not responding to tickets**

<Tooltip tip="The ticket may not be assigned to the AI user, or Autopilot may be disabled. OpenCX only processes tickets assigned to the default user ID.">Likely cause</Tooltip>: ticket not assigned to the AI user, Autopilot disabled, or the message sender is not the customer.

**Fix:** check these in order:

1. Confirm the ticket is assigned to the Gorgias user ID you entered as the **Default User ID** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias.
2. Confirm [Autopilot](https://platform.open.cx/settings/autopilot) is enabled.
3. Confirm the message was sent by the customer, not by an agent or an internal note.
4. Check the [Inbox](https://platform.open.cx/inbox) for the session — if a session exists, the webhook is working but the AI may have decided not to reply (check the AI reasoning).

### **Handoff fires but ticket is not routed to an agent**

<Tooltip tip="On handoff, OpenCX reassigns the ticket to the default user/team via the Gorgias API. If no Gorgias workflow rule picks up the assignment change, the ticket stays in queue without a specific agent.">Likely cause</Tooltip>: no Gorgias workflow rule is configured to route tickets after handoff, or the default team ID is not set.

**Fix:** check these in order:

1. Confirm you have a Gorgias workflow rule that triggers when a ticket is assigned to your handoff team and routes it to the right agent.
2. If you are not using a default team, consider configuring one in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias (this requires re-saving settings via the API, as the dashboard currently exposes the user ID but not the team ID).
3. Check the [Inbox](https://platform.open.cx/inbox) for the session — the handoff event should be visible. If it is, the issue is on the Gorgias routing side.

### **Duplicate AI replies on the same message**

<Tooltip tip="The deduplication window expired (1-hour TTL) or the same message text was sent on a different ticket within the window.">Likely cause</Tooltip>: dedup window expired or webhook retried after the window.

**Fix:** OpenCX deduplicates messages by content hash with a 1-hour window. If Gorgias retries a webhook delivery after the window expires, a duplicate can occur. This is rare — if it happens consistently, check that your Gorgias webhook is not configured to retry aggressively.

### **AI replies appearing as the wrong user**

<Tooltip tip="AI replies are posted via the Gorgias API and appear as messages from the API integration, not from a specific Gorgias user.">Likely cause</Tooltip>: this is expected behavior. AI replies are posted through the Gorgias REST API and appear as API-sourced messages. The sender name is "AI Assistant."

**Fix:** this is not a bug. To control how the reply appears to customers, configure your Gorgias email templates and auto-reply settings.

### **AI keeps replying after handoff**

<Tooltip tip="The session should be in a handed-off state, which prevents further AI processing. If this happens, the session state may not have been updated correctly.">Likely cause</Tooltip>: the session was not properly marked as handed off, or a new session was created for the same ticket.

**Fix:** check the session in [Inbox](https://platform.open.cx/inbox). If the session shows as handed off, the AI should not be replying. If you see a second session for the same ticket, the deduplication window may have expired (24-hour ticket lock). Contact [support](mailto:mo@open.cx) with the session ID.

### **None of the above**

If your issue does not match any scenario above, contact [support](mailto:mo@open.cx) with the Gorgias ticket ID, the OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)), and a description of the expected vs actual behavior.

## Limits and timing

|                                  | Value                                                                       |
| -------------------------------- | --------------------------------------------------------------------------- |
| **Message deduplication window** | 1 hour                                                                      |
| **Ticket lock duration**         | 24 hours                                                                    |
| **Webhook token**                | Signed per-organization, does not expire unless credentials are regenerated |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Gorgias" icon="plug" href="/integrations/gorgias/connect">
    Re-verify credentials and webhook setup.
  </Card>

  <Card title="Ticket Flow" icon="diagram-project" href="/integrations/gorgias/ticket-flow">
    How messages flow and how handoff works.
  </Card>

  <Card title="Gorgias Overview" icon="cart-shopping" href="/integrations/gorgias/overview">
    What the integration does and supported channels.
  </Card>

  <Card title="Handoff Settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>