name: zendesk-insights description: "Analyze Zendesk support data for ticket insights and team performance. Use when asked about: ticket analysis, customer complaints, biggest issues, ticket trends, response times, resolution metrics, CSAT scores, satisfaction ratings, agent performance, team performance, support quality, channel breakdown, real inbound volume, daily KPI report, or Zendesk helpdesk data." metadata: {"openclaw": {"requires": {"env": ["ZENDESK_SUBDOMAIN", "ZENDESK_EMAIL", "ZENDESK_API_TOKEN"]}, "primaryEnv": "ZENDESK_API_TOKEN"}}

Zendesk Insights

Analyze Zendesk tickets and support performance. Analysis scripts pre-compute aggregations so you only interpret results.

Prerequisites

Set credentials via environment variables, .env file, or openclaw.json:

ZENDESK_SUBDOMAIN=yourcompany
ZENDESK_EMAIL=admin@yourcompany.com
ZENDESK_API_TOKEN=your-api-token

Quick Start

Full KPI report (recommended — most complete):

py {baseDir}/scripts/report_kpi.py --since 2025-01-01

Ticket analysis (what are customers complaining about?):

py {baseDir}/scripts/analyze_tickets.py --since 2025-01-01 --classify

Performance dashboard (how is the team doing?):

py {baseDir}/scripts/analyze_performance.py --since 2025-01-01 --classify

Workflows

Use Case 1: Full KPI Report

1. Run report_kpi.py --since YYYY-MM-DD
2. Output includes: real_inbound_per_day, channel/source breakdowns, SLA by channel, CSAT, top concerns with samples, volume trends
3. Interpret: compare SLA across channels, identify worst CSAT themes, spot staffing gaps from busiest hours/days
4. Present as an executive dashboard with actionable recommendations

Use Case 2: Ticket Analysis

1. Run analyze_tickets.py --since YYYY-MM-DD --classify
2. Output includes: by_status, by_priority, by_tag, keywords, time patterns, AND by_channel_norm, by_source_norm, real_inbound_count, auto_generated_count
3. Without --classify: same as before (no channel/source/inbound classification)
4. Identify top complaint categories, note auto-generated noise level, read sample descriptions

Use Case 3: Performance Metrics

1. Run analyze_performance.py --since YYYY-MM-DD --classify
2. Output includes: reply/resolution/wait time stats + per-channel SLA breakdown
3. Without --classify: flat overall stats only (backward compatible)

Use Case 4: Historical Backfill

1. Run zd_incremental.py --start-date YYYY-MM-DD for initial full pull
2. Run zd_incremental.py --continue for daily syncs
3. Checkpoint auto-saved to ~/.zendesk-insights/checkpoint.json

Drilling Deeper

# Raw tickets
py {baseDir}/scripts/zd_tickets.py --search "type:ticket status:open tags:billing"

# Ticket comments for theme analysis
py {baseDir}/scripts/zd_comments.py --ticket-ids 123,456 --public-only

# Ticket audits for classification verification
py {baseDir}/scripts/zd_audits.py --ticket-ids 123,456 --first-only

# User role lookup
py {baseDir}/scripts/zd_users.py --ids 123,456

# Raw metrics / CSAT
py {baseDir}/scripts/zd_metrics.py --ticket-ids 123,456
py {baseDir}/scripts/zd_satisfaction.py --score bad --since 2025-01-01

Script Reference

report_kpi.py — Unified KPI Report (most complete)

py {baseDir}/scripts/report_kpi.py --since YYYY-MM-DD [--until YYYY-MM-DD]
    [--max-pages N] [--no-classify] [--cache-file PATH]

analyze_tickets.py — Ticket Analysis

py {baseDir}/scripts/analyze_tickets.py --recent N | --since YYYY-MM-DD
    [--until] [--status] [--priority] [--tags] [--limit N] [--max-pages N]
    [--classify] [--cache-file PATH]

analyze_performance.py — Performance Dashboard

py {baseDir}/scripts/analyze_performance.py --since YYYY-MM-DD
    [--until] [--limit N] [--max-pages N] [--classify] [--cache-file PATH]

zd_incremental.py — Incremental Export

py {baseDir}/scripts/zd_incremental.py --start-date YYYY-MM-DD
py {baseDir}/scripts/zd_incremental.py --continue
    [--checkpoint-file PATH] [--max-pages N] [--output-file PATH]

zd_tickets.py — Raw Tickets

py {baseDir}/scripts/zd_tickets.py --recent N | --all | --search QUERY
    [--status] [--since] [--until] [--priority] [--tags] [--limit N]

zd_comments.py — Ticket Comments

py {baseDir}/scripts/zd_comments.py --ticket-ids 1,2,3 [--public-only] [--limit N]

zd_audits.py — Ticket Audits

py {baseDir}/scripts/zd_audits.py --ticket-ids 1,2,3 [--first-only]

zd_users.py — User Lookup

py {baseDir}/scripts/zd_users.py --ids 1,2,3 | --from-tickets
    [--cache-file PATH] [--no-cache]

zd_metrics.py — Raw Metrics

py {baseDir}/scripts/zd_metrics.py --all | --ticket-ids 1,2,3 | --since YYYY-MM-DD
    [--limit N]

zd_satisfaction.py — Raw CSAT

py {baseDir}/scripts/zd_satisfaction.py --all | --score good|bad
    [--since] [--until] [--count] [--limit N]

zd_common.py — Auth Check

py {baseDir}/scripts/zd_common.py

Classification

When --classify is used (or via report_kpi.py), tickets get these added fields:

• channel_norm: email, chat, voice, web_form, sms, social, api, automation, other
• source_norm: walmart, amazon, tiktok, web_widget, other
• is_real_inbound: true if customer-initiated and not auto-generated
• auto_generated: true if created by rule/automation/trigger
• inbound_kind: customer, system, agent, unknown

Rules are in references/classification_rules.json — edit to add custom mappings.

Search Query Syntax

For --search flag, see references/api_reference.md. Common patterns:

• type:ticket status:open priority:urgent
• type:ticket created>2025-01-01 tags:billing
• type:ticket status:open -tags:spam