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

# Zendesk integration

> Install SiteGPT as a Zendesk AI agent with one-click OAuth — no API keys, no webhook setup

<video controls className="w-full aspect-video" src="https://mintlify.s3.us-west-1.amazonaws.com/sitegpt/videos/zendesk.mp4" />

Connect your SiteGPT chatbot to Zendesk Messaging in about two minutes.
One-click OAuth install, no API keys, no webhook configuration. SiteGPT
becomes your default AI agent — handling customer conversations, answering
from your knowledge base, and handing off to human agents when needed.

<Note>If you already have the older API-key-based Zendesk integration installed, see [Zendesk (Legacy)](/integrations/zendesk-legacy). For new Zendesk installs, follow this guide.</Note>

## How it works

<CardGroup cols={2}>
  <Card title="One-click install" icon="bolt">
    OAuth flow — no API keys, no secrets, no webhooks to configure
  </Card>

  <Card title="AI as default responder" icon="robot">
    SiteGPT answers every new conversation from your knowledge base
  </Card>

  <Card title="Seamless agent handoff" icon="handshake">
    Escalates to human agents through Zendesk's native switchboard
  </Card>

  <Card title="Auto-resume after resolve" icon="arrows-rotate">
    When an agent solves the ticket, SiteGPT automatically resumes
  </Card>
</CardGroup>

## Prerequisites

<Check>Zendesk Suite **Professional** plan or above, with Messaging and Sunshine Conversations access</Check>
<Check>Admin access to your Zendesk Admin Center</Check>
<Check>A trained SiteGPT chatbot ready to deploy</Check>

## Setup

Setup has two parts: **connecting SiteGPT to Zendesk** (one click), and
**one Zendesk-side configuration step** in Admin Center — connecting the
bot to your channels. No conversation-control changes and no triggers are
required.

### Part 1 — Connect SiteGPT to Zendesk

You can start the install from **either** side. Both paths end on the same
post-install walkthrough.

<Tabs>
  <Tab title="From the Zendesk Marketplace" icon="store">
    The primary path — use this if you're discovering SiteGPT from the
    marketplace listing.

    <Steps>
      <Step title="Find the listing in the Zendesk Marketplace">
        Open the [Zendesk Marketplace apps
        directory](https://www.zendesk.com/marketplace/apps), search
        for **SiteGPT AI Chatbot**, and click **Install** on the
        listing. Zendesk redirects you to `https://sitegpt.ai/connect-zendesk`.
      </Step>

      <Step title="Pick the chatbot to connect">
        Sign in to SiteGPT if you're not already. You'll see a picker
        listing the chatbots on your account that you have permission
        to connect integrations for.

        Click **Connect** next to the chatbot you want Zendesk to use.
        A **Connected** badge on any row means that chatbot already has
        an active Zendesk install — click **Manage** on those to jump
        to the integration settings page instead of re-running OAuth.

        <Info>Don't have a chatbot yet? The picker shows a **Create a chatbot** CTA. Train a chatbot first, then come back to `https://sitegpt.ai/connect-zendesk` and the picker will list it.</Info>
      </Step>

      <Step title="Authorize on Zendesk">
        Zendesk opens an OAuth consent page. Sign in with your Zendesk
        admin account, confirm the subdomain, and click **Allow**.

        SiteGPT automatically registers the Sunshine Conversations
        webhook and your chatbot appears in your Zendesk account as a
        marketplace bot. You'll land on a **You're connected!**
        walkthrough with the Admin Center steps below.
      </Step>
    </Steps>
  </Tab>

  <Tab title="From the SiteGPT dashboard" icon="browser">
    Use this path if you already have a SiteGPT account and want to add
    Zendesk to an existing chatbot.

    <Steps>
      <Step title="Open the integration page">
        In SiteGPT, open the chatbot you want to connect, then go to
        **Integrations** → **Zendesk**.
      </Step>

      <Step title="Click Connect to Zendesk">
        Click **Connect to Zendesk**. You'll be redirected to Zendesk's
        OAuth consent page.
      </Step>

      <Step title="Authorize on Zendesk">
        Sign in with your Zendesk admin account, confirm the subdomain,
        and click **Allow**. SiteGPT registers the webhook and you
        return to the integration settings page with the integration
        marked **Connected to \<subdomain>.zendesk.com**. The **View
        setup instructions** button on that page opens the same
        Admin Center walkthrough covered in Part 2.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Part 2 — Configure Zendesk Admin Center

One setting is required, then test.

<Steps>
  <Step title="Connect SiteGPT to your Web Widget">
    In Zendesk Admin Center, go to **AI** → **AI agents**. Scroll to
    the **Other** section and click **Manage marketplace bots**.

    Click **SiteGPT AI Chatbot** in the list to open its settings.
    Under **Basics → Connect to channels**, tick the checkbox next to
    your **Web** channel, click **Save**, and confirm the dialog.

    The **Responder** column for that channel switches from
    *Basic response* to **SiteGPT AI Chatbot**.

    <Info>This routes every new inbound conversation on that channel to SiteGPT. Without this step, Zendesk's default responder keeps ownership and SiteGPT never sees customer messages.</Info>

    <Note>We recommend starting with the **Web Widget** channel — it's the only Zendesk Messaging surface where lead-collection forms, reply chips, and other rich UI elements render. WhatsApp, Facebook Messenger, SMS, and other third-party channels support plain chat but not forms. You can add them later for chat-only flows.</Note>
  </Step>

  <Step title="Test the integration">
    Open the Zendesk Web Widget on your website (or use Zendesk's
    preview).

    Send a test message. SiteGPT should reply immediately with an
    AI-generated answer based on your training data.

    Test the full escalation flow:

    1. Type a message that should escalate (e.g. "I want to talk to a
       human") — SiteGPT hands off to a Zendesk agent.
    2. Reply as an agent in Zendesk's agent workspace — the customer
       sees the agent reply in the widget.
    3. When the conversation is done, resolve the ticket and click
       **End session** in the conversation's composer (the reply-editor
       area) — the customer's next message is answered by SiteGPT
       again.

    <Note>Don't see **End session**? It's hidden until an admin enables it: **Admin Center** → **Channels** → **Messaging and social** → **Messaging** → **Manage settings** → **Advanced** → **Ending sessions** → select **"Agents can end messaging sessions at any time"** → Save. See [Zendesk's guide](https://support.zendesk.com/hc/en-us/articles/8372292195354-Allowing-agents-to-end-messaging-sessions).</Note>

    <Info>Hand-back works with either **Conversation control** setting (Pass control or Release control) — you don't need to change it.</Info>
  </Step>
</Steps>

### Optional — hand back on Solved without the extra click

By default, agents end the messaging session (**End session**) after
resolving, which returns the conversation to SiteGPT. If your team
prefers hand-back to happen automatically when a ticket is marked
**Solved**, add this trigger. It is entirely optional.

Go to **Objects and rules** → **Business rules** → **Triggers** →
**Create trigger**.

<Tabs>
  <Tab title="Trigger details" icon="wrench">
    * **Trigger name**: `Solved → Closed (messaging only)`
    * **Trigger category**: any (Notifications works)
  </Tab>

  <Tab title="Conditions" icon="filter">
    Under **Meet ALL of the following conditions**, add both:

    | Category               | Operator | Value     |
    | ---------------------- | -------- | --------- |
    | Ticket > Ticket status | Is       | Solved    |
    | Ticket > Channel       | Is       | Messaging |
  </Tab>

  <Tab title="Action" icon="play">
    Add:

    | Category                 | Value  |
    | ------------------------ | ------ |
    | Ticket > Status category | Closed |
  </Tab>
</Tabs>

Save the trigger.

<Warning>The **Channel Is Messaging** condition matters — without it, the trigger would also promote your email tickets from Solved to Closed.</Warning>

## What happens during a conversation

<AccordionGroup>
  <Accordion title="Normal AI-handled conversation" icon="robot">
    1. Customer opens the Zendesk Web Widget and sends a message.
    2. Zendesk routes the message to SiteGPT (because SiteGPT is
       connected as the responder for that channel).
    3. SiteGPT answers from your knowledge base.
    4. No Zendesk ticket is created — the conversation stays in the
       messaging channel.

    Conversations that never escalate don't consume a ticket.
  </Accordion>

  <Accordion title="Escalation to a human agent" icon="handshake">
    1. SiteGPT detects the customer wants human help (keyword, low
       confidence, explicit request, etc.).
    2. SiteGPT calls Zendesk's switchboard to **pass control** to the
       agent workspace.
    3. A Zendesk ticket is created at this moment.
    4. The agent replies in Zendesk — the reply appears in the
       customer's widget.
    5. SiteGPT stops responding while the agent has control.
  </Accordion>

  <Accordion title="Resolving and resuming AI" icon="arrows-rotate">
    1. The agent finishes the conversation, marks the ticket
       **Solved**, and clicks **End session** in the Agent Workspace
       conversation controls (or your optional `Solved → Closed`
       trigger fires — see the optional section above).
    2. Zendesk ends the messaging session and returns conversation
       control to SiteGPT.
    3. The customer's next message is answered by SiteGPT again.
       SiteGPT also releases its switchboard hold once the interaction
       has concluded, per Zendesk's marketplace-bot guidelines —
       because SiteGPT is your channel's responder, follow-up messages
       still route to it.
  </Accordion>

  <Accordion title="Lead collection mid-conversation" icon="address-book">
    When your chatbot's lead-collection rules are triggered, SiteGPT
    shows a native Zendesk form inside the widget with the fields
    you've configured (name, email, phone, and any required custom
    fields).

    <Warning>Lead-collection forms only render on the **Web Widget** and the **Zendesk Messaging iOS/Android SDKs**. Third-party channels (WhatsApp, Facebook Messenger, SMS, Instagram, etc.) don't have a form primitive in their underlying protocols — Sunshine Conversations falls back to plain text, which is a broken UX for structured capture. If you need lead collection on those channels, handle it conversationally (AI-prompted capture) rather than via a form.</Warning>

    * Only **required** custom fields are forwarded to Zendesk —
      Sunshine Conversations forms treat every field as required, so
      optional fields are collected only on SiteGPT's side.
    * Zendesk caps forms at 20 fields. Base fields (name / email /
      phone) count against that limit.
    * Field labels are truncated to 200 characters before sending.

    Submitted leads appear in your SiteGPT Leads inbox and in the
    Zendesk ticket transcript.
  </Accordion>
</AccordionGroup>

## Customization

**In SiteGPT:**

* Update bot name and avatar in [appearance settings](/features/appearance).
* Modify response tone in [chatbot settings](/navigating-your-chatbot/settings).
* Configure [conversation starters](/features/conversation-starters) and [follow-up suggestions](/features/conversation-followups).
* Set up [human support](/features/human-support) rules and [lead collection](/features/lead-collection).

**In Zendesk:**

* Customize widget color, brand name, and business hours.
* Configure how agents receive and respond to handed-off conversations.
* Use Zendesk Explore for ticket and conversation analytics.

Changes in SiteGPT take effect immediately — no reconnection required.

## Managing the integration

<Tabs>
  <Tab title="Monitor performance" icon="chart-line">
    **In SiteGPT:**

    * Open **Chat History** to review every Zendesk conversation.
    * See which conversations stayed with AI vs. escalated to agents.
    * Export conversation data for analysis.

    **In Zendesk:**

    * Track tickets created by escalation vs. direct ticket creation.
    * Use Zendesk Explore for ticket volume and deflection reporting.
    * Monitor agent workload reduction.
  </Tab>

  <Tab title="Disconnect" icon="plug">
    **From SiteGPT:**

    1. Open the chatbot's **Integrations** → **Zendesk** page.
    2. Click **Disconnect**.

    SiteGPT removes the webhook from Zendesk and marks the
    installation as disconnected. Your bot stops receiving new
    conversations immediately.

    **From Zendesk (optional):**

    * Go to **AI** → **AI agents** → **Other** → **Marketplace bots**
      → **Manage marketplace bots**, open the three-dot menu on
      **SiteGPT AI Chatbot**, and **Uninstall**. This notifies SiteGPT
      via the uninstall callback.

    Existing conversation history remains in both platforms.
  </Tab>

  <Tab title="Reconnect" icon="arrows-rotate">
    If you've disconnected, go back to **Integrations** → **Zendesk**
    in SiteGPT and click **Connect to Zendesk** again. You can also
    start from `https://sitegpt.ai/connect-zendesk` and pick the chatbot from
    the list.

    You'll skip straight through the OAuth consent (Zendesk remembers
    the prior authorization) and the installation is reactivated.
  </Tab>

  <Tab title="Switch to a different chatbot" icon="right-left">
    Each Zendesk account connects to one SiteGPT chatbot at a time.
    To swap which chatbot answers Zendesk conversations:

    1. Disconnect the current chatbot (see **Disconnect** tab).
    2. Go to `https://sitegpt.ai/connect-zendesk`, pick the new chatbot, and
       click **Connect**.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="SiteGPT isn't responding to new conversations" icon="circle-xmark">
    The most common cause is that the Web channel isn't connected to
    SiteGPT inside the bot's settings.

    Check: **Admin Center** → **AI** → **AI agents** → **Other** →
    **Manage marketplace bots** → click **SiteGPT AI Chatbot** → under
    **Basics → Connect to channels**, the **Web** channel should be
    ticked and its **Responder** column should read **SiteGPT AI
    Chatbot** (not **Basic response**).

    If Basic response is still the responder, tick the Web channel
    checkbox, save, and confirm the dialog — that flips Zendesk's
    routing from the default responder to SiteGPT.
  </Accordion>

  <Accordion title="The conversation stays with the agent after the ticket is solved" icon="triangle-exclamation">
    Marking a ticket **Solved** doesn't end the messaging session by
    itself. Two ways to hand the conversation back to SiteGPT:

    1. The agent clicks **End session** in the conversation's composer
       after resolving — the built-in path.
    2. If you've added the optional `Solved → Closed (messaging only)`
       trigger, check that it exists and is **Active** — a disabled
       trigger leaves the ticket in Solved and the session open with
       the agent.
  </Accordion>

  <Accordion title="Agents don't see an End session option" icon="eye-slash">
    The End session control is hidden until an admin enables it.

    Go to **Admin Center** → **Channels** → **Messaging and social** →
    **Messaging** → **Manage settings** → **Advanced** → **Ending
    sessions**, select **"Agents can end messaging sessions at any
    time"**, and save. The option then appears in the messaging
    conversation's composer. See [Zendesk's
    guide](https://support.zendesk.com/hc/en-us/articles/8372292195354-Allowing-agents-to-end-messaging-sessions).
  </Accordion>

  <Accordion title="The lead form isn't rendering on Zendesk" icon="input-text">
    Only **required** custom fields are forwarded to Zendesk
    (Sunshine Conversations treats every form field as required).
    If a field is configured as optional in SiteGPT's lead settings,
    it won't appear on the Zendesk side.

    To collect a field on Zendesk, mark it required in the chatbot's
    lead-collection settings. If you have more than \~17 required
    custom fields plus the base name / email / phone fields, trailing
    fields may be dropped — Zendesk caps forms at 20 fields.
  </Accordion>

  <Accordion title="Install failed with a 'connection' or 'webhook' error" icon="plug-circle-xmark">
    The post-OAuth webhook registration step can fail on Zendesk's
    side for transient reasons.

    1. Go to `https://sitegpt.ai/connect-zendesk`, pick the chatbot, and
       click **Connect** to retry the full install.
    2. If retrying doesn't help, contact [support@sitegpt.ai](mailto:support@sitegpt.ai) with your
       chatbot ID and Zendesk subdomain — we can inspect the
       installation state directly.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Human support" icon="user-headset" href="/features/human-support">
    Configure escalation triggers and routing
  </Card>

  <Card title="Lead collection" icon="address-book" href="/features/lead-collection">
    Capture and qualify leads in Zendesk conversations
  </Card>

  <Card title="Chat history" icon="messages" href="/navigating-your-chatbot/chat-history">
    Review every Zendesk conversation in SiteGPT
  </Card>

  <Card title="Chatbot instructions" icon="sparkles" href="/features/chatbot-instructions-personas">
    Tune how your bot responds
  </Card>
</CardGroup>