Monitor CSAT scores and alert Slack on detractors using a Claude Code skill

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

.claude/skills/csat-alert/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-alert.md                # Block Kit template for Slack alerts
└── references/
    └── gorgias-surveys-api.md        # Gorgias satisfaction surveys API

---
name: csat-alert
description: Check recent Gorgias satisfaction survey scores and alert Slack when a customer gives a low rating, so detractors get immediate follow-up.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Fetch recent satisfaction survey responses from Gorgias, identify low scores (1-2 out of 5 by default), and post a formatted Slack alert for each detractor. Tag the ticket in Gorgias for tracking.
 
## Configuration
 
Read these environment variables:
 
- `GORGIAS_DOMAIN` — your Gorgias subdomain (required)
- `GORGIAS_EMAIL` — Gorgias account email for API auth (required)
- `GORGIAS_API_KEY` — Gorgias API key (required)
- `SLACK_WEBHOOK_URL` — Slack Incoming Webhook URL (required)
 
Default lookback window: 2 hours. Default low-score threshold: 2 (alert on scores 1-2). The user may request different values.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch recent satisfaction surveys from Gorgias. See `references/gorgias-surveys-api.md` for the endpoint and response format.
3. For each survey with a score at or below the threshold, fetch the full ticket to get customer name, email, subject, and assigned agent.
4. Post a Slack alert using the template in `templates/slack-alert.md`.
5. Tag the ticket with `csat-low` to track which tickets triggered alerts.
6. Track already-alerted survey IDs in a local JSON file to avoid duplicate alerts across runs.
7. Print a summary of alerts sent.
 
## Important notes
 
- The Gorgias `PUT /tickets/{id}` endpoint REPLACES the entire tags array. Fetch current tags first, merge `csat-low`, then PUT the combined list.
- The satisfaction surveys endpoint returns surveys, not tickets. Each survey has a `ticket_id` you need to fetch separately for context.
- Rate limit: Gorgias allows roughly 2 requests per second. Add delays if processing many surveys.
- Store the alerted survey IDs file in the skill directory (e.g., `.alerted_surveys.json`). Keep it in `.gitignore`.
- Use the `requests` library for HTTP calls. Install with pip if needed.

# CSAT Alert Slack Template
 
Use this Block Kit structure for each low CSAT score alert.
 
## Block Kit JSON
 
```json
{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Low CSAT Score: <score>/5"
      }
    },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*Customer:* <customer_name>" },
        { "type": "mrkdwn", "text": "*Email:* <customer_email>" },
        { "type": "mrkdwn", "text": "*Subject:* <ticket_subject>" },
        { "type": "mrkdwn", "text": "*Agent:* <agent_name>" }
      ]
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "Open Ticket" },
          "url": "https://<GORGIAS_DOMAIN>.gorgias.com/app/ticket/<ticket_id>"
        }
      ]
    }
  ]
}
```
 
## Notes
 
- Send via `POST` to the `SLACK_WEBHOOK_URL` with the JSON body above.
- Replace all `<placeholders>` with actual values from the survey and ticket data.
- If the survey includes a text comment, add it as an additional section block.

# Gorgias Satisfaction Surveys API Reference
 
## Authentication
 
All requests use HTTP Basic Auth:
- Username: `GORGIAS_EMAIL`
- Password: `GORGIAS_API_KEY`
- Base URL: `https://{GORGIAS_DOMAIN}.gorgias.com/api`
 
## List satisfaction surveys
 
Fetch recent satisfaction survey responses.
 
**Request:**
 
```
GET /api/satisfaction-surveys?created_datetime__gte=<iso_datetime>&limit=50&order_by=created_datetime:desc
```
 
**Response shape:**
 
```json
{
  "data": [
    {
      "id": 5001,
      "score": 1,
      "body_text": "Waited 5 days and still no resolution",
      "ticket_id": 10384,
      "created_datetime": "2026-03-05T10:30:00+00:00"
    }
  ]
}
```
 
- `score` is 1-5 (1 = very dissatisfied, 5 = very satisfied).
- `body_text` may be null if the customer didn't leave a comment.
- Use `ticket_id` to fetch the full ticket for customer and agent context.
 
## Get a single ticket
 
**Request:**
 
```
GET /api/tickets/{ticket_id}
```
 
**Response shape:**
 
```json
{
  "id": 10384,
  "subject": "Damaged item, no replacement sent",
  "status": "closed",
  "requester": {
    "id": 678,
    "name": "Priya Nair",
    "email": "priya@example.com"
  },
  "assignee_user": {
    "id": 42,
    "name": "Jordan M."
  },
  "tags": [
    { "name": "shipping" }
  ]
}
```
 
## Update a ticket (add tag)
 
**Request:**
 
```
PUT /api/tickets/{ticket_id}
Content-Type: application/json
```
 
**IMPORTANT:** The `tags` field REPLACES the entire array. Fetch current tags first, add `csat-low`, then PUT the merged list.
 
```json
{
  "tags": [
    { "name": "shipping" },
    { "name": "csat-low" }
  ]
}
```

/csat-alert

Checking CSAT surveys from the last 2 hours...
Found 8 recent survey response(s)
 
  #15201  Score: 1/5  Customer: Maria S.
    Subject: Damaged item received
    -> Slack alert sent, tagged csat-low
 
  #15198  Score: 5/5  (above threshold, skipped)
  #15195  Score: 2/5  Customer: James T.
    Subject: Late delivery
    -> Slack alert sent, tagged csat-low
 
Done. Sent 2 Slack alert(s).

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

name: CSAT Alert Monitor
on:
  schedule:
    - cron: '*/30 * * * *'  # Every 30 minutes
  workflow_dispatch: {}
jobs:
  alert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /csat-alert"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GORGIAS_DOMAIN: ${{ secrets.GORGIAS_DOMAIN }}
          GORGIAS_EMAIL: ${{ secrets.GORGIAS_EMAIL }}
          GORGIAS_API_KEY: ${{ secrets.GORGIAS_API_KEY }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}