> ## 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.

# Connect Gorgias

> Enter your Gorgias API credentials, copy the webhook URL, and configure the default assignee for AI-processed tickets.

export const GorgiasFlow = () => {
  const BEAM_COLOR = "#22c55e";
  const renderBeam = ({id, d, duration = 2.8, delay = 0, reverse = false}) => {
    const values = reverse ? {
      x1: "110%;-10%",
      x2: "120%;0%"
    } : {
      x1: "-10%;110%",
      x2: "0%;120%"
    };
    return <g key={id}>
        <path d={d} stroke="currentColor" strokeOpacity="0.18" strokeWidth="1.5" fill="none" strokeLinecap="round" />
        <path d={d} stroke={`url(#${id})`} strokeWidth="2" fill="none" strokeLinecap="round" />
        <defs>
          <linearGradient id={id} gradientUnits="userSpaceOnUse" x1="0" y1="0" x2="0" y2="0">
            <stop offset="0%" stopColor={BEAM_COLOR} stopOpacity="0" />
            <stop offset="45%" stopColor={BEAM_COLOR} stopOpacity="1" />
            <stop offset="55%" stopColor={BEAM_COLOR} stopOpacity="1" />
            <stop offset="100%" stopColor={BEAM_COLOR} stopOpacity="0" />
            <animate attributeName="x1" values={values.x1} dur={`${duration}s`} begin={`${delay}s`} repeatCount="indefinite" />
            <animate attributeName="x2" values={values.x2} dur={`${duration}s`} begin={`${delay}s`} repeatCount="indefinite" />
          </linearGradient>
        </defs>
      </g>;
  };
  const CH_X = 80, GOR_X = 340, OCX_X = 600, TEAM_X = 830;
  const Y = 160, R = 40;
  const channelYs = [110, 160, 210];
  const channelLabels = ["email", "chat", "social · phone"];
  const chBeams = channelYs.map((y, i) => ({
    id: `gorg-ch-${i}`,
    d: `M ${CH_X + 24},${y} C ${CH_X + 100},${y} ${GOR_X - R - 60},${Y} ${GOR_X - R},${Y}`,
    delay: i * 0.35
  }));
  const mainB = `M ${GOR_X + R},${Y} C ${GOR_X + 100},${Y - 30} ${OCX_X - R - 100},${Y - 30} ${OCX_X - R},${Y}`;
  const mainBRev = `M ${GOR_X + R},${Y} C ${GOR_X + 100},${Y + 30} ${OCX_X - R - 100},${Y + 30} ${OCX_X - R},${Y}`;
  const handoffB = `M ${OCX_X + R},${Y} C ${OCX_X + 80},${Y - 30} ${TEAM_X - 40},${Y - 30} ${TEAM_X - 28},${Y}`;
  return <div className="zendesk-flow not-prose my-8 w-full">
      <div className="zendesk-flow-frame relative w-full overflow-hidden rounded-md border border-black/10 bg-white px-4 py-6 dark:border-white/10 dark:bg-zinc-950">
        <div className="zendesk-flow-grid pointer-events-none absolute inset-0" aria-hidden />
        <svg viewBox="0 0 900 320" preserveAspectRatio="xMidYMid meet" xmlns="http://www.w3.org/2000/svg" className="relative z-[1] block w-full text-zinc-500 dark:text-zinc-400" role="img" aria-label="Gorgias flow: all channels funnel through a single Gorgias webhook; OpenCX escalates by reassigning the ticket to a default team">
          {chBeams.map(b => renderBeam({
    id: b.id,
    d: b.d,
    duration: 3.0,
    delay: b.delay
  }))}
          {renderBeam({
    id: "gorg-m",
    d: mainB,
    duration: 2.6,
    delay: 0
  })}
          {renderBeam({
    id: "gorg-mr",
    d: mainBRev,
    duration: 2.6,
    delay: 1.3,
    reverse: true
  })}
          {renderBeam({
    id: "gorg-h",
    d: handoffB,
    duration: 3.0,
    delay: 0.6
  })}

          {}
          {channelYs.map((y, i) => <text key={`gl-${i}`} x={CH_X + 40} y={y + 4} className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "500 10.5px ui-sans-serif, system-ui, sans-serif"
  }}>
              · {channelLabels[i]}
            </text>)}

          <g className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "500 11px ui-sans-serif, system-ui, sans-serif"
  }}>
            <text x={(GOR_X + OCX_X) / 2} y={Y - 46} textAnchor="middle">ticket · AI reply</text>
            <text x={(OCX_X + TEAM_X) / 2} y={Y - 42} textAnchor="middle">reassign on handoff</text>
          </g>

          {}
          <g>
            <rect x={CH_X - 24} y={channelYs[0] - 16} width="48" height={channelYs[2] - channelYs[0] + 32} rx="8" className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" />
            <g transform={`translate(${CH_X - 10} ${(channelYs[0] + channelYs[2]) / 2 - 24})`} className="fill-none stroke-zinc-700 dark:stroke-zinc-200" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round">
              <circle cx="10" cy="8" r="4" />
              <path d="M 2 23 C 2 17 18 17 18 23" />
            </g>
            <text x={CH_X} y={channelYs[2] + 34} textAnchor="middle" className="fill-zinc-700 dark:fill-zinc-200" style={{
    font: "600 12px ui-sans-serif, system-ui, sans-serif"
  }}>Customer</text>
          </g>

          {}
          <g>
            <circle cx={GOR_X} cy={Y} r={R} className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" />
            <foreignObject x={GOR_X - 20} y={Y - 20} width="40" height="40">
              <div className="flex h-full w-full items-center justify-center">
                <img src="/images/integrations/gorgias.svg" alt="" className="h-7 w-7 object-contain" />
              </div>
            </foreignObject>
            <text x={GOR_X} y={Y + R + 22} textAnchor="middle" className="fill-zinc-700 dark:fill-zinc-200" style={{
    font: "600 12px ui-sans-serif, system-ui, sans-serif"
  }}>Gorgias</text>
            <text x={GOR_X} y={Y + R + 36} textAnchor="middle" className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "400 10.5px ui-sans-serif, system-ui, sans-serif"
  }}>single webhook</text>
          </g>

          {}
          <g>
            <circle cx={OCX_X} cy={Y} r={R + 4} className="fill-none" stroke={BEAM_COLOR} strokeOpacity="0.25" strokeWidth="1.5">
              <animate attributeName="r" values={`${R + 2};${R + 12};${R + 2}`} dur="3.6s" repeatCount="indefinite" />
              <animate attributeName="stroke-opacity" values="0.35;0;0.35" dur="3.6s" repeatCount="indefinite" />
            </circle>
            <circle cx={OCX_X} cy={Y} r={R} className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" />
            <foreignObject x={OCX_X - 30} y={Y - 16} width="60" height="32">
              <div className="flex h-full w-full items-center justify-center">
                <img src="/logo-light.svg" alt="" className="block h-full w-full object-contain dark:hidden" />
                <img src="/logo.svg" alt="" className="hidden h-full w-full object-contain dark:block" />
              </div>
            </foreignObject>
            <text x={OCX_X} y={Y + R + 22} textAnchor="middle" className="fill-zinc-700 dark:fill-zinc-200" style={{
    font: "600 12px ui-sans-serif, system-ui, sans-serif"
  }}>OpenCX</text>
            <text x={OCX_X} y={Y + R + 36} textAnchor="middle" className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "400 10.5px ui-sans-serif, system-ui, sans-serif"
  }}>AI agent</text>
          </g>

          {}
          <g>
            <rect x={TEAM_X - 40} y={Y - 28} width="80" height="56" rx="10" className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" strokeDasharray="3 3" />
            {}
            <g className="fill-zinc-500 dark:fill-zinc-400">
              <circle cx={TEAM_X - 14} cy={Y - 4} r="7" />
              <circle cx={TEAM_X} cy={Y - 4} r="7" className="fill-zinc-600 dark:fill-zinc-300" />
              <circle cx={TEAM_X + 14} cy={Y - 4} r="7" />
              <path d={`M ${TEAM_X - 22} ${Y + 10} C ${TEAM_X - 22} ${Y + 4} ${TEAM_X - 6} ${Y + 4} ${TEAM_X - 6} ${Y + 10}`} fill="currentColor" />
              <path d={`M ${TEAM_X - 8} ${Y + 10} C ${TEAM_X - 8} ${Y + 4} ${TEAM_X + 8} ${Y + 4} ${TEAM_X + 8} ${Y + 10}`} className="fill-zinc-600 dark:fill-zinc-300" />
              <path d={`M ${TEAM_X + 6} ${Y + 10} C ${TEAM_X + 6} ${Y + 4} ${TEAM_X + 22} ${Y + 4} ${TEAM_X + 22} ${Y + 10}`} fill="currentColor" />
            </g>
            <text x={TEAM_X} y={Y + 36} textAnchor="middle" className="fill-zinc-700 dark:fill-zinc-200" style={{
    font: "600 12px ui-sans-serif, system-ui, sans-serif"
  }}>Default team</text>
            <text x={TEAM_X} y={Y + 50} textAnchor="middle" className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "400 10.5px ui-sans-serif, system-ui, sans-serif"
  }}>on escalation</text>
          </g>
        </svg>
      </div>
    </div>;
};

One-time setup: enter your Gorgias API key and domain, set a default assignee for handoffs, and paste the webhook URL into Gorgias so customer messages reach OpenCX.

<GorgiasFlow />

<Info>
  This page covers the Gorgias connection setup. Once connected, see [Ticket Flow](/integrations/gorgias/ticket-flow) for how messages are processed and handed off.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Gorgias account with API access" icon="key">
    You need a Gorgias helpdesk on a plan that includes REST API access. You also need admin permissions to create API keys and configure webhooks.
  </Accordion>

  <Accordion title="Admin access in OpenCX" icon="shield-check">
    Only organization admins can connect integrations. Confirm your role at [**Settings → Organization**](https://platform.open.cx/settings).
  </Accordion>

  <Accordion title="A dedicated Gorgias user for the AI" icon="user">
    The AI only processes tickets assigned to a specific Gorgias user. Create a dedicated user (e.g. "AI Agent") in Gorgias so your reps can distinguish AI-handled tickets from their own.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Generate an API key in Gorgias">
    In your Gorgias helpdesk, go to **Settings → REST API** and create a new API key with full access.

    The API key is a Base64-encoded string combining your email and token. Gorgias shows this on the REST API page.

    <Warning>
      Store the API key securely — you will need it in the next step. If you lose it, revoke and regenerate from the same Gorgias settings page.
    </Warning>
  </Step>

  <Step title="Find your domain prefix">
    Your domain prefix is the subdomain of your Gorgias helpdesk URL. If your helpdesk is at `acme.gorgias.com`, the domain prefix is `acme`.
  </Step>

  <Step title="Find your default user ID">
    The default user ID is the Gorgias user the AI operates as. To find it:

    1. Go to **Settings → REST API** in Gorgias.
    2. Open the API explorer or use the `/users` endpoint.
    3. Find the user you created for the AI and note their numeric ID.

    <Note>
      The AI only processes tickets assigned to this user. Tickets assigned to anyone else are ignored — your human agents' work is never interrupted.
    </Note>
  </Step>

  <Step title="Enter credentials in OpenCX">
    Open [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard. Select **Gorgias** and enter:

    | Field               | Value                                                         |
    | ------------------- | ------------------------------------------------------------- |
    | **API Key**         | The Base64-encoded API key from Gorgias Settings → REST API.  |
    | **Domain Prefix**   | Your Gorgias subdomain (e.g. `acme` from `acme.gorgias.com`). |
    | **Default User ID** | The numeric Gorgias user ID for the AI agent.                 |

    Click **Test & Save**. OpenCX validates the credentials by calling the Gorgias API. If validation fails, double-check that the API key has not been revoked and the domain prefix is correct.
  </Step>

  <Step title="Copy the webhook URL into Gorgias">
    After credentials are saved, OpenCX displays a webhook URL. Copy it and configure a webhook in Gorgias:

    1. In Gorgias, go to **Settings → Integrations → HTTP Integration** (or **Settings → Webhooks** depending on your Gorgias version).
    2. Create a new webhook with the URL you copied from OpenCX.
    3. Subscribe to **ticket message created** events so Gorgias notifies OpenCX when customers send messages.

    <Warning>
      Without the webhook, OpenCX cannot receive ticket messages. The AI will not respond to anything until the webhook is active and pointing to the correct URL.
    </Warning>
  </Step>

  <Step title="Send a test message">
    Create a test ticket in Gorgias (or have a customer send a message) assigned to your AI user. The AI should reply on the ticket within a few seconds.

    To test handoff, send a message like *"I want to talk to a human."* The ticket should be reassigned to your default user or team.
  </Step>
</Steps>

## Settings reference

All settings are configured at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Gorgias.

| Setting             | Purpose                                                                                | Required |
| ------------------- | -------------------------------------------------------------------------------------- | -------- |
| **API Key**         | Authenticates OpenCX with the Gorgias API. Base64-encoded.                             | Yes      |
| **Domain Prefix**   | Your Gorgias subdomain (e.g. `acme`). Determines the API endpoint.                     | Yes      |
| **Default User ID** | The Gorgias user the AI operates as. Only tickets assigned to this user are processed. | Yes      |

## Configure a Gorgias workflow for handoff routing

After setup, create a workflow rule in Gorgias to route handed-off tickets to your human agents. When the AI hands off, it reassigns the ticket to the configured default team. A Gorgias rule that triggers on team assignment can then route the ticket to the right agent.

<Info>
  Without a workflow rule, handed-off tickets stay in the default team's queue but are not automatically assigned to a specific agent. Your reps can still pick them up manually.
</Info>

## Disconnecting

To remove the Gorgias integration, open [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Gorgias and click **Disconnect** (or delete the saved credentials). This stops webhook processing. Existing OpenCX sessions are preserved but no longer receive updates from Gorgias.

<Note>
  Also remove the webhook URL from your Gorgias settings to stop Gorgias from sending events to an inactive endpoint.
</Note>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Ticket Flow" icon="diagram-project" href="/integrations/gorgias/ticket-flow">
    How messages flow, handoff behavior, and what your reps see.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/gorgias/troubleshooting">
    Credentials failing, webhook silent, AI not replying.
  </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>