Automate first responses to Gorgias tickets using a Claude Code skill

mkdir -p .claude/skills/first-response/{templates,references}

.claude/skills/first-response/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── drafting-prompt.md            # system prompt for Claude reply drafting
└── references/
    ├── gorgias-tickets-api.md        # Gorgias API patterns
    └── knowledge-base.md             # your support FAQs and policies

---
name: first-response
description: Find Gorgias tickets with no agent reply and draft a contextual first response using Claude, posted as an internal note for agent review or sent directly.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Find open Gorgias tickets that have no agent reply yet, draft a contextual first response using Claude (Haiku), and post it to Gorgias as either an internal note (default) or a public reply.
 
## 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)
- `ANTHROPIC_API_KEY` — Anthropic API key for Claude drafting (required)
- `AUTO_SEND` — set to "true" to send as public reply instead of internal note (optional, default: false)
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Fetch open tickets from Gorgias. See `references/gorgias-tickets-api.md` for the endpoint.
3. Filter to tickets where no message has `source.type == "helpdesk"` (no agent reply yet).
4. For each ticket, read the customer's message body and subject.
5. Read the knowledge base from `references/knowledge-base.md` and the drafting prompt from `templates/drafting-prompt.md`.
6. Call the Anthropic API (claude-haiku-4-5) with the drafting prompt, knowledge base, and ticket content to generate a reply.
7. Post the drafted response to Gorgias via `POST /tickets/{id}/messages`. Set `public: false` by default (internal note) or `public: true` if AUTO_SEND is enabled.
8. Print each ticket ID, subject, and a preview of the draft.
 
## Important notes
 
- Default to internal notes (`public: false`). Only send as public replies when the user explicitly asks or sets `AUTO_SEND=true`.
- Use claude-haiku-4-5 for drafting — it's fast and inexpensive (~$0.003 per reply).
- Keep draft replies under 150 words. Customers prefer concise answers.
- The knowledge base in `references/knowledge-base.md` must be kept up to date with current policies. Stale information produces inaccurate replies.
- Use the `requests` library for Gorgias API calls and `anthropic` for Claude. Install with pip if needed.

# First Response Drafting Prompt
 
Use this system prompt when calling Claude to draft a reply.
 
## System Prompt
 
```
You are a friendly, concise customer support agent for an e-commerce store.
 
Use the knowledge base below to write a helpful first response to this customer's message. Keep the response under 150 words. Be warm but efficient. Don't over-apologize.
 
Write only the reply body — no subject line, no "Dear", just the message content starting with "Hi [name],".
```
 
## User Prompt Template
 
```
Knowledge base:
{knowledge_base_content}
 
Customer name: {customer_name}
Subject: {subject}
Message: {body_first_800_chars}
```
 
## Notes
 
- Use `claude-haiku-4-5-20251001` as the model for cost efficiency (~$0.003 per reply).
- Set `max_tokens: 300` to keep replies concise.
- Replace `{customer_name}` with `ticket.requester.firstname` or "there" if unavailable.
- Only include the first 800 characters of the message body to stay within prompt limits.

# 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 open tickets
 
**Request:**
 
```
GET /api/tickets?status=open&limit=20
```
 
**Response shape:**
 
```json
{
  "data": [
    {
      "id": 12345,
      "subject": "Where is my order?",
      "status": "open",
      "requester": {
        "id": 678,
        "firstname": "Sarah",
        "email": "sarah@example.com"
      },
      "messages": [
        {
          "id": 99001,
          "body_text": "Hi, I placed an order 3 days ago...",
          "source": { "type": "email" },
          "created_datetime": "2026-03-05T10:00:00+00:00"
        }
      ]
    }
  ]
}
```
 
- To find tickets needing a first reply: filter for tickets where NO message has `source.type == "helpdesk"`.
- The first message in the `messages` array is typically the customer's original message.
 
## Post a message on a ticket
 
**Request:**
 
```
POST /api/tickets/{ticket_id}/messages
Content-Type: application/json
```
 
**Body (internal note):**
 
```json
{
  "body_text": "Draft reply text here...",
  "body_html": "<p>Draft reply text here...</p>",
  "channel": "email",
  "from_agent": true,
  "public": false,
  "source": {
    "type": "helpdesk",
    "from": {
      "name": "Support Team",
      "address": "support@<GORGIAS_DOMAIN>.com"
    }
  }
}
```
 
- Set `public: false` for internal notes (agent review before sending).
- Set `public: true` for direct customer-facing replies.
- The `body_html` field accepts simple HTML — convert newlines to `<p>` tags.

# Support Knowledge Base
 
Update this file with your current policies and FAQs. Claude uses this content to draft accurate replies.
 
## Order Tracking
- Tracking emails are sent within 24 hours of shipping
- Track at: https://yourstore.com/tracking
- Orders ship in 1-2 business days; delivery takes 3-5 business days
 
## Returns
- 30-day return window from delivery date
- Items must be unused and in original packaging
- Start a return at: https://yourstore.com/returns
- Refunds process within 5-7 business days after we receive the item
 
## Order Changes and Cancellations
- Orders can be changed or cancelled within 1 hour of placement
- After 1 hour, contact us immediately — we'll try but can't guarantee changes
 
## International Shipping
- We ship to 40+ countries
- International delivery: 7-14 business days
- Customs fees are the customer's responsibility

/first-response

Looking for tickets with no agent reply...
Found 5 ticket(s) needing a first response
 
  #14801  "Where is my order?"  →  posted as internal note
    Draft: Hi Sarah, Thanks for reaching out! Your order shipped yesterday...
 
  #14805  "Return request for jacket"  →  posted as internal note
    Draft: Hi James, Happy to help with your return! You can start the...
 
Done. Processed 5 ticket(s).

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

name: First Response Drafts
on:
  schedule:
    - cron: '*/30 13-22 * * 1-5'  # 8 AM-5 PM ET, weekdays
  workflow_dispatch: {}
jobs:
  draft:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /first-response"
          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 }}