GroundTruth
Back to Docs
Integration

Zendesk

Automatically flag AI-generated replies that contain unsupported or hallucinated claims — directly inside your Zendesk tickets as internal notes. No code to write, no scripts to paste into Zendesk.

How the integration works

  1. Zendesk sends ticket events (new replies, AI-drafted messages) to GroundTruth.
  2. Our system runs claim verification against your knowledge base.
  3. If a reply is high-risk, our system calls the Zendesk API to add an internal note to that ticket explaining the issue.

All processing happens on our servers. You configure Zendesk through its admin UI — there is no code to deploy or maintain.

Recommended

Option A: Zendesk App

The production-ready integration. Best UX, enterprise-friendly, and no manual webhook setup.

1. Install the GroundTruth app

  1. In Zendesk, go to Admin Center → Apps and Integrations → Zendesk Marketplace.
  2. Search for "GroundTruth" and click Install.
  3. Alternatively, if your organization uses private apps, your admin can install the app via a provided URL.

2. Connect your Zendesk account

  1. Open the GroundTruth app inside Zendesk (it appears in the sidebar).
  2. Click "Connect Zendesk".
  3. You'll be redirected to authorize access via OAuth. If OAuth is not available in your Zendesk plan, you can use an API token instead.

3. Configure settings

After connecting, toggle the options that match your workflow:

SettingWhat it does
Check AI-generated repliesSends drafted AI replies to GroundTruth for verification before they are sent to the customer.
Add internal note on high-risk repliesWhen a reply is flagged, an internal note is added to the ticket explaining the risk and suggesting a safe rewrite.
Block sending high-risk repliesOptional. Prevents high-risk replies from being sent until an agent reviews them.

What happens behind the scenes

  1. Zendesk sends us the ticket ID, drafted reply text, and metadata (channel, author type, timestamp).
  2. Our system runs hallucination and claim verification against your knowledge base.
  3. If the reply is high-risk, our system calls the Zendesk API to add an internal note to the ticket. The note includes the risk score, which claims were unsupported, and a safe rewrite if available.
  4. If "Block sending" is enabled, the reply is held until an agent approves or edits it.

Why this option is recommended

  • Best UX — settings live inside Zendesk, no context switching.
  • Enterprise-friendly — installed via Marketplace, managed by your Zendesk admin.
  • No manual webhook setup — the app handles all connections automatically.
  • Easier permissions — OAuth scoping and lifecycle managed through the app.
Alternative

Option B: Webhook + Trigger

A faster setup that doesn't require installing a Zendesk app. Good for testing or MVPs. Everything is configured in the Zendesk admin UI.

1. Create a webhook in Zendesk

  1. Go to Admin Center → Apps & Integrations → Webhooks → Create Webhook.
  2. Fill in the fields:
FieldValue
NameAI Reply Risk Check
Endpoint URLhttps://api.groundtruth.com/webhooks/zendesk
Request methodPOST
Request formatJSON
AuthenticationNone, or Bearer Token with your GroundTruth API key for added security.

2. Create a trigger to fire the webhook

  1. Go to Admin Center → Objects and Rules → Triggers → Add Trigger.
  2. Set the conditions:
  • Ticket is updated
  • AND comment is present
  • AND comment is public OR drafted by AI

Set the action:

  • Notify active webhook → select "AI Reply Risk Check"
  • JSON body: include the ticket ID, comment text, and channel
json
{
  "ticket_id": "{{ticket.id}}",
  "comment": "{{ticket.latest_comment}}",
  "channel": "{{ticket.via}}"
}

3. What happens after Zendesk sends the webhook

  1. Our system receives the ticket data and runs a risk check against your knowledge base.
  2. If the reply is high-risk, our system uses the Zendesk API to add an internal note to the ticket.
  3. The note explains which claims were unsupported and includes a safe rewrite if one is available.

If the reply is low-risk, nothing happens — no note is added.

Limitations

Compared to the Zendesk App (Option A).

  • Flag only — cannot block replies from being sent, only adds internal notes after the fact.
  • More setup — requires manually creating a webhook and trigger in Zendesk.
  • No in-app UI — there are no toggle controls inside Zendesk; changes require editing the trigger.
Technical Reference

How internal notes are added

The code below runs on our servers, not yours. You never need to write, paste, or deploy any code. This is shown for transparency so you understand what happens when a high-risk reply is detected.

What this code does, in plain English

  1. Our server receives the verification result (from either Option A or Option B).
  2. If the verdict is not high-risk, it does nothing and responds with a success status.
  3. If the verdict is high-risk, it calls the Zendesk API to update the ticket.
  4. It adds an internal note (not visible to the customer) that includes the risk score and whether a safe rewrite is available.

Server-side code (runs on our infrastructure)

This is not something you need to deploy. It is shown for reference only.

node.js
// This code runs on GroundTruth servers.
// You do NOT need to write or deploy this yourself.

app.post("/webhooks/zendesk", async (req, res) => {
  const event = req.body;

  // If the reply is not high-risk, do nothing
  if (event.data.verdict !== "high_risk") {
    return res.sendStatus(200);
  }

  // Add an internal note to the Zendesk ticket
  const ticketId = event.data.ticket_id;
  await fetch(
    `https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/${ticketId}.json`,
    {
      method: "PUT",
      headers: {
        Authorization: `Bearer ${ZENDESK_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        ticket: {
          comment: {
            // Internal note — not visible to the customer
            body: `GroundTruth flagged this reply (risk score: ${event.data.risk_score}). ${event.data.has_rewrite ? "A safe rewrite is available in the dashboard." : "Manual review is recommended."}`,
            public: false,
          },
        },
      }),
    }
  );

  res.sendStatus(200);
});
Knowledge Base

Sync Help Center articles

In addition to flagging risky replies, you can sync your Zendesk Help Center articles into GroundTruth so verification checks run against your actual support documentation.

How to sync

  1. Go to Settings in the GroundTruth dashboard.
  2. Under Zendesk, click "Sync" to pull articles into your Library.
  3. Up to 50 published Help Center articles are synced per request. Article bodies are converted from HTML to plain text.
  4. Click "Sync" again any time to pull updated or new articles.

Sync via API

Automate syncing programmatically.

api
POST /api/integrations/sync
{ "provider": "zendesk" }

# Response
{
  "success": true,
  "provider": "zendesk",
  "documentsFound": 42,
  "documentsIngested": 42
}