Audit VIP Zendesk tickets using a Claude Code skill

mkdir -p .claude/skills/zendesk-vip-audit/{templates,references}

.claude/skills/zendesk-vip-audit/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-alert.md                # Block Kit template for VIP alerts
└── references/
    └── zendesk-orgs-api.md           # Zendesk organizations and tickets API patterns

---
name: zendesk-vip-audit
description: Audit recent Zendesk tickets for missed VIP flags and post alerts to Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Find open Zendesk tickets from VIP organizations that were not tagged as VIP. For each missed ticket, add the `vip` tag, set priority to Urgent, optionally assign to the VIP Support group, and post a Slack alert.
 
## 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)
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch all organizations and filter to those tagged with "vip" to build a set of VIP org IDs. See `references/zendesk-orgs-api.md`.
3. Fetch groups to get the VIP Support group ID. See `references/zendesk-orgs-api.md`.
4. Search for open/pending tickets that do NOT have the `vip` tag. See `references/zendesk-orgs-api.md`.
5. For each ticket, check if its `organization_id` matches a VIP org. If yes:
   a. Update the ticket: add `vip` tag (merged with existing tags), set priority to `urgent`, optionally set `group_id` to VIP Support.
   b. Post a Slack alert using the format in `templates/slack-alert.md`.
6. Print a summary of how many missed VIP tickets were found and flagged.
 
## Important notes
 
- VIP status is determined by organization tags, not ticket tags. Check the ticket's `organization_id` against VIP org IDs.
- The Zendesk PUT endpoint replaces the entire tags array. Merge existing tags with the new `vip` tag before updating.
- 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 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.
- This skill is a safety net behind the Zendesk trigger. It catches tickets that slipped through, not a replacement for real-time escalation.

# Zendesk Organizations & Tickets API Reference
 
## Authentication
 
All Zendesk API requests use Basic Auth. The username is `email/token:api_token` (note the `/token` suffix).
 
```
Authorization: Basic base64(email/token:api_token)
```
 
Base URL: `https://{subdomain}.zendesk.com/api/v2`
 
## List organizations
 
Fetch all organizations to find VIP-tagged ones.
 
**Request:**
 
```
GET https://{subdomain}.zendesk.com/api/v2/organizations.json?per_page=100
Authorization: Basic <credentials>
```
 
**Response shape:**
 
```json
{
  "organizations": [
    {
      "id": 12345,
      "name": "Acme Corp",
      "tags": ["vip", "enterprise"]
    },
    {
      "id": 67890,
      "name": "Small Co",
      "tags": []
    }
  ],
  "next_page": null
}
```
 
Filter to organizations where `"vip"` is in the `tags` array to build a set of VIP org IDs.
 
Note: Paginate using `next_page` if you have more than 100 organizations.
 
## Search for untagged open tickets
 
Find tickets that don't have the `vip` tag.
 
**Request:**
 
```
GET https://{subdomain}.zendesk.com/api/v2/search.json?query=type:ticket status:open status:pending -tags:vip&per_page=100
Authorization: Basic <credentials>
```
 
**Response shape:**
 
```json
{
  "results": [
    {
      "id": 48291,
      "subject": "SSO login broken for our team",
      "organization_id": 12345,
      "tags": ["technical"],
      "status": "open",
      "priority": "normal"
    }
  ],
  "count": 47
}
```
 
The `organization_id` field links to the ticket requester's organization. Check this against VIP org IDs.
 
## Update a ticket
 
**Request:**
 
```
PUT https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json
Authorization: Basic <credentials>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "ticket": {
    "tags": ["existing-tag", "vip"],
    "priority": "urgent",
    "group_id": 12345
  }
}
```
 
Important: `tags` replaces the entire array. Merge existing tags with the new `vip` tag.
 
## List groups
 
```
GET https://{subdomain}.zendesk.com/api/v2/groups.json
```
 
Response: `{"groups": [{"id": 12345, "name": "VIP Support"}]}`
 
## Rate limits
 
~700 requests/minute on Professional plans. This audit uses 1 orgs call + 1 groups call + 1 search call + 1 PUT per flagged ticket.

# Slack VIP Alert Template
 
Use this Block Kit structure for each missed VIP ticket alert.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Missed VIP ticket #<ticket_id>: <subject>",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Missed VIP Ticket Flagged",
        "emoji": true
      }
    },
    {
      "type": "section",
      "fields": [
        {"type": "mrkdwn", "text": "*Ticket:* <ticket_url|#ticket_id>"},
        {"type": "mrkdwn", "text": "*Subject:* <subject>"},
        {"type": "mrkdwn", "text": "*Organization:* <org_name>"},
        {"type": "mrkdwn", "text": "*Priority:* Urgent (escalated)"}
      ]
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "This ticket was from a VIP org but wasn't tagged. It's been flagged and escalated."
        }
      ]
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {"type": "plain_text", "text": "View in Zendesk"},
          "url": "<ticket_url>",
          "style": "danger"
        }
      ]
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback.
- Ticket URL format: `https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}`
- Use the `danger` button style to visually signal that this ticket was missed.
- Include the organization name so agents know which VIP account is affected.

/zendesk-vip-audit

Loading VIP organizations...
  Found 12 VIP organization(s)
 
Checking 47 untagged tickets...
  #98234  "Cannot access billing portal"  →  flagged as VIP (Acme Corp)
  #98251  "API rate limit question"  →  flagged as VIP (Widget Inc)
 
Flagged 2 missed VIP ticket(s) out of 47 checked.

# Run every hour during business hours
0 8-18 * * 1-5 cd /path/to/your/project && claude -p "Run /zendesk-vip-audit" --allowedTools 'Bash(*)' 'Read(*)'

name: VIP Audit
on:
  schedule:
    - cron: '0 13-22 * * 1-5'  # 8 AM-5 PM ET, hourly
  workflow_dispatch: {}   # Manual trigger for testing
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /zendesk-vip-audit"
          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 }}