Auto-close stale Gorgias tickets using a Claude Code skill

mkdir -p .claude/skills/auto-close-stale/{templates,references}

.claude/skills/auto-close-stale/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── closing-message.md            # follow-up message template
└── references/
    └── gorgias-tickets-api.md        # Gorgias API patterns

---
name: auto-close-stale
description: Find Gorgias tickets with no customer reply after 48 hours, send a follow-up message, and close tickets where the follow-up was already sent and 24 more hours have passed.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Find pending Gorgias tickets where the agent replied but the customer hasn't responded within a configurable window (default: 48 hours). Send a follow-up message to those tickets. On a subsequent run, close tickets that already received a follow-up and still have no customer reply after an additional 24 hours (72 hours total).
 
## Configuration
 
Read these environment variables:
 
- `GORGIAS_DOMAIN` — your Gorgias subdomain, e.g. "yourstore" (required)
- `GORGIAS_EMAIL` — Gorgias account email for API auth (required)
- `GORGIAS_API_KEY` — Gorgias API key (required)
 
Default thresholds: follow-up after 48 hours, close after 72 hours total. The user may request different windows.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch pending tickets from Gorgias filtered to `status=pending`. See `references/gorgias-tickets-api.md` for the endpoint and response format.
3. For each ticket, calculate hours since `updated_datetime`. Check that the last message is from an agent (source type `helpdesk`). Skip tickets tagged `vip`, `escalated`, or `priority`.
4. For tickets past the follow-up threshold (default 48h) that are NOT tagged `auto-close-sent`, send a follow-up message using the template in `templates/closing-message.md`, then tag the ticket `auto-close-sent`.
5. For tickets already tagged `auto-close-sent` that are past the close threshold (default 72h), set the ticket status to `closed` and add the `auto-closed` tag.
6. Print a summary of follow-ups sent and tickets closed.
 
## Important notes
 
- The Gorgias `PUT /tickets/{id}` endpoint REPLACES the entire tags array. You must GET the current tags first, merge your new tag in, then PUT the combined list. If you send only the new tag, all existing tags are removed.
- Rate limit: Gorgias allows roughly 2 requests per second. Add a small delay between API calls if processing many tickets.
- Always support a `--dry-run` flag that previews actions without making changes.
- Use the `requests` library for HTTP calls. Install with pip if needed.

# Closing Follow-Up Message Template
 
Use this template when sending a follow-up message to a stale ticket before closing.
 
## Message Body
 
```
Hi {customer_name},
 
Just checking in — did our previous reply resolve your question? If you still need help, simply reply to this message and we'll pick things right back up.
 
If we don't hear from you, we'll close this ticket shortly to keep things tidy. You can always reach out again anytime.
 
Best,
The Support Team
```
 
## API Payload
 
Send via `POST /api/tickets/{ticket_id}/messages`:
 
```json
{
  "body_text": "<message body above with {customer_name} replaced>",
  "channel": "email",
  "from_agent": true,
  "source": {
    "type": "helpdesk",
    "from": {
      "name": "Support Team",
      "address": "support@<GORGIAS_DOMAIN>.com"
    }
  }
}
```
 
## Notes
 
- Replace `{customer_name}` with `ticket.requester.firstname` or "there" if not available.
- The `from_agent: true` flag ensures the message shows as an agent reply, not a customer message.
- The `source.type` must be `helpdesk` so Gorgias counts this as an agent message.

# Gorgias Tickets 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 tickets
 
Fetch tickets filtered by status.
 
**Request:**
 
```
GET /api/tickets?status=pending&limit=50
```
 
**Response shape:**
 
```json
{
  "data": [
    {
      "id": 12345,
      "subject": "Question about return policy",
      "status": "pending",
      "updated_datetime": "2026-03-01T14:30:00+00:00",
      "created_datetime": "2026-03-01T10:00:00+00:00",
      "requester": {
        "id": 678,
        "firstname": "Sarah",
        "email": "sarah@example.com"
      },
      "tags": [
        { "name": "shipping" }
      ],
      "messages": [
        {
          "id": 99001,
          "body_text": "Customer message here...",
          "source": { "type": "email" },
          "created_datetime": "2026-03-01T10:00:00+00:00"
        },
        {
          "id": 99002,
          "body_text": "Agent reply here...",
          "source": { "type": "helpdesk" },
          "created_datetime": "2026-03-01T11:00:00+00:00"
        }
      ]
    }
  ]
}
```
 
- Check `messages[-1].source.type == "helpdesk"` to confirm the last message is from an agent.
- Parse `updated_datetime` to calculate hours since last activity.
- Tags are objects with a `name` field.
 
## Send a message on a ticket
 
**Request:**
 
```
POST /api/tickets/{ticket_id}/messages
Content-Type: application/json
```
 
See `templates/closing-message.md` for the payload structure.
 
## Update a ticket (tags, status)
 
**Request:**
 
```
PUT /api/tickets/{ticket_id}
Content-Type: application/json
```
 
**IMPORTANT:** The `tags` field REPLACES the entire array. To add a tag without removing existing ones:
 
1. Read the current ticket to get existing tags
2. Merge your new tag into the list
3. PUT the combined array
 
**Body to close a ticket:**
 
```json
{
  "status": "closed",
  "tags": [
    { "name": "existing-tag-1" },
    { "name": "auto-closed" }
  ]
}
```
 
**Body to add a tag:**
 
```json
{
  "tags": [
    { "name": "existing-tag-1" },
    { "name": "auto-close-sent" }
  ]
}
```

/auto-close-stale

Fetching pending tickets from Gorgias...
Found 24 pending ticket(s)
 
  Sent follow-up: #14201 "Return policy question" (52h stale)
  Sent follow-up: #14198 "Shipping delay" (49h stale)
  Closed: #14185 "Order status inquiry" (74h stale, follow-up already sent)
  Skipped: #14190 "VIP account issue" (tagged vip)
 
Done. Follow-ups sent: 2, Tickets closed: 1

# Run every hour on the hour
0 * * * * cd /path/to/your/project && claude -p "Run /auto-close-stale" --allowedTools 'Bash(*)' 'Read(*)'

name: Auto-Close Stale Tickets
on:
  schedule:
    - cron: '0 * * * *'  # Every hour
  workflow_dispatch: {}   # Manual trigger for testing
jobs:
  close:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /auto-close-stale"
          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 }}