Send a Slack alert when a Pipedrive deal changes stage using a Claude Code skill

mkdir -p .claude/skills/pd-deal-stage-alerts/{templates,references}

.claude/skills/pd-deal-stage-alerts/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-alert.md                # Block Kit template for Slack messages
└── references/
    └── pipedrive-deals-api.md        # Pipedrive API patterns

---
name: pd-deal-stage-alerts
description: Check for recent Pipedrive deal stage changes and post alerts to Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Check for Pipedrive deals modified in a given time window (default: last 1 hour) and post a formatted alert per deal to a Slack channel.
 
## Configuration
 
Read these environment variables:
 
- `PIPEDRIVE_API_TOKEN` — Pipedrive API token from Settings > Personal > Tools and Integrations > API (required)
- `PIPEDRIVE_COMPANY_DOMAIN` — your Pipedrive subdomain, e.g. "yourcompany" from yourcompany.pipedrive.com (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 the list of pipeline stages from Pipedrive so you can resolve numeric `stage_id` values to human-readable names. See `references/pipedrive-deals-api.md` for the endpoint.
3. Query Pipedrive for deals modified in the lookback window using the Recents endpoint. See `references/pipedrive-deals-api.md` for the query and response shape.
4. For each deal, post a message to Slack using the Block Kit format in `templates/slack-alert.md`.
5. Print a summary of how many alerts were posted.
 
## Important notes
 
- Pipedrive updates deal timestamps on ANY field change, not just stage changes. Some results may not be actual stage transitions. Mention this in your summary.
- Stage IDs in Pipedrive are numeric (e.g., `stage_id: 3`). You must resolve them to human-readable names via the `/v1/stages` endpoint before posting alerts.
- The API token does not expire (unlike OAuth tokens). It remains valid until the user regenerates it in Pipedrive settings.
- `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 `urllib.request` for HTTP calls (no external dependencies required).

# Slack Alert Template
 
Use this Block Kit structure for each Pipedrive deal stage change alert.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Deal stage changed: <deal_title>",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":arrows_counterclockwise: *Deal Stage Changed*\n*<deal_title>* is now in *<stage_name>*\nValue: $<deal_value>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "<<pipedrive_link>|View in Pipedrive>"
        }
      ]
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback for notifications and accessibility.
- The Pipedrive deal link format: `https://<PIPEDRIVE_COMPANY_DOMAIN>.pipedrive.com/deal/<DEAL_ID>`.
- Format the value with comma separators (e.g., $75,000 not $75000).
- `value` may be null if not set on the deal. Display "N/A" when null.
- To customize, you can add fields like organization name, owner, expected close date, or stage transition (previous → current).

# Pipedrive Deals API Reference
 
## Fetch pipeline stages
 
Resolve numeric stage IDs to human-readable stage names.
 
**Request:**
 
```
GET https://api.pipedrive.com/v1/stages
```
 
**Headers / query params:**
 
```
api_token=<PIPEDRIVE_API_TOKEN>
```
 
**Response shape:**
 
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Qualified Lead",
      "pipeline_id": 1,
      "order_nr": 1
    },
    {
      "id": 2,
      "name": "Discovery",
      "pipeline_id": 1,
      "order_nr": 2
    },
    {
      "id": 3,
      "name": "Proposal Sent",
      "pipeline_id": 1,
      "order_nr": 3
    }
  ]
}
```
 
Build a dictionary mapping `id` → `name` so you can look up stage labels for each deal.
 
## Query recently modified deals
 
Use the Recents endpoint to find deals modified within a time window.
 
**Request:**
 
```
GET https://api.pipedrive.com/v1/recents?since_timestamp=<ISO_TIMESTAMP>&items=deal&limit=500
```
 
**Headers / query params:**
 
```
api_token=<PIPEDRIVE_API_TOKEN>
```
 
- `since_timestamp` is an ISO 8601 datetime string (e.g., `2026-03-06T13:00:00Z`). Calculate it by subtracting the lookback window from the current time.
- `items=deal` restricts results to deals only.
- `limit` controls page size (max 500).
 
**Response shape:**
 
```json
{
  "success": true,
  "data": [
    {
      "item": "deal",
      "id": 98765,
      "data": {
        "id": 98765,
        "title": "Meridian Health Platform Migration",
        "value": 75000,
        "currency": "USD",
        "status": "open",
        "stage_id": 3,
        "pipeline_id": 1,
        "owner_id": 12345,
        "org_id": 11111,
        "person_id": 54321,
        "expected_close_date": "2026-05-20",
        "update_time": "2026-03-06T14:30:00Z"
      }
    }
  ],
  "additional_data": {
    "pagination": {
      "start": 0,
      "limit": 500,
      "more_items_in_collection": false,
      "next_start": 500
    }
  }
}
```
 
## Additional useful fields
 
The deal object includes `org_id` and `person_id` for related records. To include organization or contact names, query those separately:
 
```
GET https://api.pipedrive.com/v1/organizations/<org_id>?api_token=<PIPEDRIVE_API_TOKEN>
GET https://api.pipedrive.com/v1/persons/<person_id>?api_token=<PIPEDRIVE_API_TOKEN>
```
 
## Notes
 
- Pipedrive uses numeric `stage_id` values, not human-readable names. Always resolve via the `/v1/stages` endpoint.
- `value` is a number (not a string). It may be null if the deal value hasn't been set.
- The `more_items_in_collection` field indicates whether additional pages exist. If `true`, use `start=<next_start>` to fetch the next page.
- API tokens do not expire. They remain valid until regenerated in Pipedrive settings.
- Rate limits: token-based daily budget (30,000 base tokens x plan multiplier x seats). A single deal fetch costs 1 token. A 429 response means the daily budget is exhausted.

/pd-deal-stage-alerts

Checking for deals modified in the last 1 hour(s)...
  Fetched 8 pipeline stages
  Found 3 modified deal(s)
  Posted: Meridian Health Platform Migration → Proposal Sent
  Posted: Contoso Platform Expansion → Negotiation
  Posted: Acme Corp Annual Renewal → Closed Won
Done. Posted 3 alert(s) to Slack.
Note: Pipedrive updates timestamps on any field change, so some alerts
may be for non-stage modifications.

# Run every hour on the hour
0 * * * * cd /path/to/your/project && claude -p "Run /pd-deal-stage-alerts" --allowedTools 'Bash(*)' 'Read(*)'

name: Pipedrive Deal Stage Alerts
on:
  schedule:
    - cron: '0 * * * *'  # Every hour
  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 /pd-deal-stage-alerts"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PIPEDRIVE_API_TOKEN: ${{ secrets.PIPEDRIVE_API_TOKEN }}
          PIPEDRIVE_COMPANY_DOMAIN: ${{ secrets.PIPEDRIVE_COMPANY_DOMAIN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}