Skip to main content

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.

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.
If you already have the older API-key-based Zendesk integration installed, see Zendesk (Legacy). For new Zendesk installs, follow this guide.

​
How it works

One-click install

OAuth flow — no API keys, no secrets, no webhooks to configure

AI as default responder

SiteGPT answers every new conversation from your knowledge base

Seamless agent handoff

Escalates to human agents through Zendesk’s native switchboard

Auto-resume after resolve

When an agent solves the ticket, SiteGPT automatically resumes

​
Prerequisites

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

​
Setup

Setup has two parts: connecting SiteGPT to Zendesk (one click), and three Zendesk-side configuration steps in Admin Center. All three Zendesk-side steps are required for escalation and hand-back to work correctly.

​
Part 1 — Connect SiteGPT to Zendesk

You can start the install from either side. Both paths end on the same post-install walkthrough.
The primary path — use this if you’re discovering SiteGPT from the marketplace listing.
1

Find the listing in the Zendesk Marketplace

Open the Zendesk Marketplace apps directory, search for SiteGPT AI Chatbot, and click Install on the listing. Zendesk redirects you to https://sitegpt.ai/connect-zendesk.
2

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

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.

​
Part 2 — Configure Zendesk Admin Center

Three settings are required — all in Zendesk’s Admin Center.
1

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

Set Conversation control to 'Pass control'

Still in Admin Center, go to Channels → Messaging and social → Messaging → click Manage settings (top-right of the Messaging list page).Scroll to Conversation control → Switchboard action → select Pass control.
Do not select “Release control” — this breaks the hand-back flow. When a ticket is resolved, SiteGPT needs Zendesk to pass conversation control back to the bot, which only happens in Pass control mode.
3

Create a 'Solved → Closed' trigger

This trigger automatically closes Zendesk tickets when an agent marks them as Solved, which is what returns the conversation to SiteGPT.Go to Objects and rules → Business rules → Triggers → Create trigger.
  • Trigger name: Solved → Closed
  • Trigger category: any (Notifications works)
Save the trigger.
Zendesk’s trigger UI doesn’t expose “Status is Closed” directly, so we promote Solved to Closed via this trigger. When the ticket hits the Closed status category, Zendesk ends the messaging session and hands control back to SiteGPT.
Do not use the “Messaging session → End session” action as an alternative — it ends the widget connection entirely and the customer can’t send a follow-up message.
4

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. Mark the ticket as Solved — the “Solved → Closed” trigger fires, and SiteGPT resumes responding in the same widget conversation.

​
What happens during a conversation

  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.
  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.
  1. The agent finishes the conversation and marks the ticket Solved.
  2. The Solved → Closed trigger fires, promoting the ticket to the Closed status category.
  3. Zendesk’s switchboard passes control back to SiteGPT.
  4. The next customer message in the same conversation is answered by SiteGPT again.
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).
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.
  • 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.

​
Customization

In SiteGPT: 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

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.

​
Troubleshooting

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.
Two things to check:
  1. Conversation control is set to Pass control (not Release control). See Part 2, Step 2.
  2. The Solved → Closed trigger exists and is Active. See Part 2, Step 3. A disabled trigger leaves the ticket in Solved (not Closed), which keeps the messaging session open with the agent.
This usually means Conversation control is set to Release control instead of Pass control. Release control breaks the hand-off path — switch to Pass control in Channels → Messaging → Manage settings → Conversation control.
You’ve likely configured a trigger action of Messaging session → End session instead of Status category = Closed. Ending the session closes the widget connection — use Status category = Closed instead (see Part 2, Step 3).
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.
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 with your chatbot ID and Zendesk subdomain — we can inspect the installation state directly.

​
Next steps

Human support

Configure escalation triggers and routing

Lead collection

Capture and qualify leads in Zendesk conversations

Chat history

Review every Zendesk conversation in SiteGPT

Chatbot instructions

Tune how your bot responds