Send Slack alerts for low Zendesk CSAT scores using a Claude Code skill

mkdir -p .claude/skills/zendesk-csat-alert/{templates,references}

.claude/skills/zendesk-csat-alert/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-alert.md                # Block Kit template for Slack messages
└── references/
    └── zendesk-csat-api.md           # Zendesk satisfaction ratings API patterns

---
name: zendesk-csat-alert
description: Check for bad Zendesk CSAT ratings and post alerts to Slack with ticket details
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Check for Zendesk satisfaction ratings with score "bad" in a given time window (default: last 1 hour) and post a formatted alert per rating to a Slack channel with full ticket context.
 
## Configuration
 
Read these environment variables:
 
- `ZENDESK_SUBDOMAIN` — Zendesk subdomain, e.g. "acme" for acme.zendesk.com (required)
- `ZENDESK_EMAIL` — Zendesk agent email for API auth (required)
- `ZENDESK_API_TOKEN` — Zendesk API token (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (required)
- `SLACK_CHANNEL_ID` — Slack channel ID starting with C (required)
 
Default lookback window: 1 hour. The user may request a different window.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch bad satisfaction ratings from Zendesk filtered to `score=bad`, sorted newest first. See `references/zendesk-csat-api.md` for the endpoint and response format.
3. Filter to ratings updated within the lookback window. If none, print "No new bad ratings found" and exit.
4. For each bad rating, fetch full ticket details (subject, requester, assignee) via the tickets endpoint. See `references/zendesk-csat-api.md` for the endpoint and response format.
5. Post a Block Kit message to Slack for each bad rating using the format in `templates/slack-alert.md`.
6. Print a summary of how many alerts were posted.
 
## Important notes
 
- Zendesk CSAT is binary: customers rate "Good" or "Bad." Any "Bad" rating warrants follow-up.
- Zendesk triggers can natively fire on satisfaction rating changes (Professional plan+), but this skill adds batch analysis, agent filtering, trend summaries, and Block Kit formatting beyond native capabilities.
- Authentication uses Basic Auth with `email/token:api_token` format. The `/token` suffix after the email is required.
- `SLACK_CHANNEL_ID` must be the channel ID (starts with `C`), not the channel name. The `chat.postMessage` API requires the ID.
- The Slack bot must be invited to the target channel or `chat.postMessage` will fail with `not_in_channel`.
- Use only Python standard library (`urllib.request`, `json`, `base64`) — no pip dependencies needed.

# Zendesk CSAT API Reference
 
## Authentication
 
All Zendesk API requests use Basic Auth. The username is `email/token:api_token` (note the `/token` suffix after the email address).
 
```
Authorization: Basic base64(email/token:api_token)
```
 
Base URL: `https://{subdomain}.zendesk.com/api/v2`
 
## List satisfaction ratings (filtered to bad)
 
Fetch recent bad CSAT ratings, sorted newest first.
 
**Request:**
 
```
GET https://{subdomain}.zendesk.com/api/v2/satisfaction_ratings?score=bad&sort_order=desc&per_page=20
Authorization: Basic <credentials>
```
 
**Parameters:**
 
- `score=bad` — filter to only unsatisfied ratings
- `sort_order=desc` — newest first
- `per_page=20` — number of results per page (max 100)
 
**Response shape:**
 
```json
{
  "satisfaction_ratings": [
    {
      "id": 12345,
      "ticket_id": 48291,
      "score": "bad",
      "comment": "Very disappointed with the response time",
      "updated_at": "2026-03-05T14:30:00Z",
      "created_at": "2026-03-05T14:28:00Z"
    }
  ]
}
```
 
Key fields:
- `id` — unique rating ID
- `ticket_id` — the associated ticket
- `score` — always "bad" since we filter on it
- `comment` — optional customer comment explaining the rating (may be null)
- `updated_at` — use this for time-based filtering
 
## Get ticket details
 
Fetch full ticket information for context in the Slack alert.
 
**Request:**
 
```
GET https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json
Authorization: Basic <credentials>
```
 
**Response shape:**
 
```json
{
  "ticket": {
    "id": 48291,
    "subject": "Order delayed twice",
    "requester_id": 67890,
    "assignee_id": 11111,
    "status": "solved",
    "tags": ["billing", "escalation"],
    "created_at": "2026-03-03T10:00:00Z"
  }
}
```
 
Key fields:
- `subject` — ticket subject line for the alert
- `requester_id` — numeric ID of the customer (resolve via Users API if name is needed)
- `assignee_id` — numeric ID of the assigned agent (resolve via Users API if name is needed)
- `status` — current ticket status
 
## Get user details (optional)
 
Resolve a user ID to a name for richer alerts.
 
**Request:**
 
```
GET https://{subdomain}.zendesk.com/api/v2/users/{user_id}.json
Authorization: Basic <credentials>
```
 
**Response shape:**
 
```json
{
  "user": {
    "id": 67890,
    "name": "Sarah Chen",
    "email": "sarah@example.com"
  }
}
```
 
Use this to resolve `requester_id` and `assignee_id` from the ticket response into display names.
 
## Rate limits
 
Zendesk allows roughly 700 API requests per minute on Professional plans. This workflow uses 1 request for ratings + 1 per bad rating for ticket details + optionally 1-2 for user resolution. Well under 1% of rate limits.

# Slack Alert Template
 
Use this Block Kit structure for each bad CSAT rating alert.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Bad CSAT rating on #<ticket_id>: <subject>",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Bad CSAT Rating Received",
        "emoji": true
      }
    },
    {
      "type": "section",
      "fields": [
        {"type": "mrkdwn", "text": "*Ticket:* <ticket_url|#ticket_id>"},
        {"type": "mrkdwn", "text": "*Subject:* <subject>"},
        {"type": "mrkdwn", "text": "*Customer:* <requester_name>"},
        {"type": "mrkdwn", "text": "*Assignee:* <assignee_name>"}
      ]
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Customer feedback:* <comment>"
      }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {"type": "plain_text", "text": "View in Zendesk"},
          "url": "<ticket_url>"
        }
      ]
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback for notifications and accessibility. Always include it.
- The ticket URL format: `https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}`
- If the customer left no comment, display "(no comment)" instead of an empty string.
- Requester and assignee names require resolving user IDs via the Users API. If skipping resolution, show the ID instead.

/zendesk-csat-alert

Checking for bad CSAT ratings in the last 1 hour(s)...
  Found 2 new bad rating(s)
  Posted: #48291 — Order delayed twice (Bad — "Very disappointed with the response time")
  Posted: #48195 — Slow response to outage report (Bad — no comment)
Done. Posted 2 alert(s) to Slack.

# Run every 30 minutes during business hours
*/30 8-18 * * 1-5 cd /path/to/your/project && claude -p "Run /zendesk-csat-alert" --allowedTools 'Bash(*)' 'Read(*)'

name: CSAT Alert
on:
  schedule:
    - cron: '*/30 * * * *'  # Every 30 minutes
  workflow_dispatch: {}   # Manual trigger for testing
jobs:
  alert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /zendesk-csat-alert"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          ZENDESK_SUBDOMAIN: ${{ secrets.ZENDESK_SUBDOMAIN }}
          ZENDESK_EMAIL: ${{ secrets.ZENDESK_EMAIL }}
          ZENDESK_API_TOKEN: ${{ secrets.ZENDESK_API_TOKEN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}