Notify a rep in Slack when a high-intent lead books a demo using a Claude Code skill

mkdir -p .claude/skills/demo-alerts/{templates,references}

.claude/skills/demo-alerts/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-alert.md                # Block Kit message template
└── references/
    └── hubspot-demo-api.md           # HubSpot contact search + Slack API patterns

---
name: demo-alerts
description: Check for recent HubSpot demo bookings and alert reps in Slack
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Check for contacts who recently booked a demo in HubSpot and send a Slack DM to the assigned rep with the contact's details and a link to the HubSpot record. Default: check the last hour. The user may request a different lookback window.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `SLACK_BOT_TOKEN` — Slack bot token with chat:write scope (required)
- `HUBSPOT_PORTAL_ID` — HubSpot portal ID for contact links (required)
- `SLACK_FALLBACK_CHANNEL` — Fallback channel ID when no owner mapping exists (optional, default: #demo-alerts)
 
The skill also needs an owner-to-Slack mapping. Define it as a dictionary in the script:
 
```python
OWNER_TO_SLACK = {
    "12345678": "U01AAAA",  # Rep name
    "23456789": "U02BBBB",  # Rep name
}
```
 
## Workflow
 
1. Validate that `HUBSPOT_ACCESS_TOKEN`, `SLACK_BOT_TOKEN`, and `HUBSPOT_PORTAL_ID` are set. If any are missing, print the error and exit.
2. Calculate the lookback window. Default: 1 hour. The user may say "check the last 24 hours" or similar.
3. Search for contacts whose `recent_conversion_date` falls within the lookback window. See `references/hubspot-demo-api.md`.
4. Filter results to contacts whose `recent_conversion_event_name` contains "demo" (case-insensitive).
5. For each demo booking, resolve the Slack target by looking up the `hubspot_owner_id` in the owner-to-Slack mapping. Fall back to the `SLACK_FALLBACK_CHANNEL` env var if not mapped.
6. Send a Slack Block Kit message to each target using the template in `templates/slack-alert.md`. See `references/hubspot-demo-api.md` for the Slack API endpoint.
7. Print a summary: how many demo bookings found, how many alerts sent, and which reps were notified.
 
## Important notes
 
- HubSpot's `recent_conversion_date` is in milliseconds since epoch. Multiply Python's `time.time()` by 1000.
- The `recent_conversion_event_name` property contains the form name. Filter for forms that contain "demo" in the name — this avoids alerting for newsletter signups or content downloads.
- Owner-to-Slack mapping must be updated with real HubSpot owner IDs and Slack user IDs. Find owner IDs in HubSpot > Settings > Users & Teams. Find Slack user IDs by clicking a profile > three dots > Copy member ID.
- Use the `requests` library for HTTP calls. Install with pip if needed.
- HubSpot allows 150 API requests per 10 seconds. Demo bookings are typically low-volume, so rate limits are rarely an issue.
- Paginate search results using the `after` cursor from `paging.next.after`.

# HubSpot Demo Bookings + Slack API Reference
 
## Authentication
 
### HubSpot
 
```
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
### Slack
 
```
Authorization: Bearer <SLACK_BOT_TOKEN>
Content-Type: application/json
```
 
## Search for recent form conversions
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer <token>
Content-Type: application/json
```
 
**Body (contacts converted in the last N milliseconds):**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "recent_conversion_date",
          "operator": "GTE",
          "value": "<epoch_ms>"
        }
      ]
    }
  ],
  "properties": [
    "firstname", "lastname", "email", "jobtitle", "company",
    "numberofemployees", "industry", "hubspot_owner_id",
    "recent_conversion_event_name", "hs_analytics_source"
  ],
  "limit": 100
}
```
 
**Response shape:**
 
```json
{
  "total": 12,
  "results": [
    {
      "id": "12345",
      "properties": {
        "firstname": "Alex",
        "lastname": "Rivera",
        "email": "alex@techcorp.com",
        "jobtitle": "VP of Engineering",
        "company": "TechCorp",
        "numberofemployees": "500",
        "industry": "computer software",
        "hubspot_owner_id": "12345678",
        "recent_conversion_event_name": "Book a Demo",
        "hs_analytics_source": "ORGANIC_SEARCH"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "100"
    }
  }
}
```
 
Filter results where `recent_conversion_event_name` contains "demo" (case-insensitive) to separate demo bookings from other form submissions.
 
Paginate using `after` cursor until `paging.next` is absent.
 
## Send a Slack message
 
**Request:**
 
```
POST https://slack.com/api/chat.postMessage
Authorization: Bearer <SLACK_BOT_TOKEN>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "channel": "<slack_user_id_or_channel_id>",
  "text": "Demo booked: Alex Rivera at TechCorp",
  "blocks": [...]
}
```
 
The `text` field is the fallback for notifications. The `blocks` array contains the rich Block Kit message. See `templates/slack-alert.md` for the block structure.
 
**Response shape:**
 
```json
{
  "ok": true,
  "channel": "D12345678",
  "ts": "1234567890.123456"
}
```
 
If `ok` is false, check the `error` field for details (e.g., `channel_not_found`, `not_in_channel`).
 
## Rate limits
 
- HubSpot: 150 requests per 10 seconds for private apps
- Slack: 1 message per second per channel (Tier 3)

# Slack Demo Alert Template
 
Use this Block Kit structure for each demo booking alert.
 
## Block Kit JSON
 
```json
[
  {
    "type": "header",
    "text": {
      "type": "plain_text",
      "text": "🔥 Demo Booked!"
    }
  },
  {
    "type": "section",
    "fields": [
      {
        "type": "mrkdwn",
        "text": "*Name:*\n<name>"
      },
      {
        "type": "mrkdwn",
        "text": "*Title:*\n<jobtitle>"
      },
      {
        "type": "mrkdwn",
        "text": "*Company:*\n<company> (<numberofemployees> employees)"
      },
      {
        "type": "mrkdwn",
        "text": "*Industry:*\n<industry>"
      },
      {
        "type": "mrkdwn",
        "text": "*Source:*\n<hs_analytics_source>"
      },
      {
        "type": "mrkdwn",
        "text": "*Email:*\n<email>"
      }
    ]
  },
  {
    "type": "actions",
    "elements": [
      {
        "type": "button",
        "text": {
          "type": "plain_text",
          "text": "View Contact"
        },
        "url": "https://app.hubspot.com/contacts/<PORTAL_ID>/contact/<contact_id>",
        "style": "primary"
      }
    ]
  }
]
```
 
## Substitution values
 
| Placeholder | Source |
|-------------|--------|
| `<name>` | `firstname` + `lastname` from contact properties |
| `<jobtitle>` | `jobtitle` property, default "N/A" |
| `<company>` | `company` property, default "Unknown" |
| `<numberofemployees>` | `numberofemployees` property, default "?" |
| `<industry>` | `industry` property, default "Unknown" |
| `<hs_analytics_source>` | `hs_analytics_source` property, default "Unknown" |
| `<email>` | `email` property, default "N/A" |
| `<PORTAL_ID>` | From `HUBSPOT_PORTAL_ID` env var |
| `<contact_id>` | Contact `id` from search results |
 
## Fallback text
 
Set the `text` field to: `"Demo booked: <name> at <company>"` — this shows in Slack notifications and mobile previews.

/demo-alerts

Checking for demo bookings in the last hour...
  Found 2 demo bookings
 
  Alex Rivera (VP of Engineering at TechCorp) → DM to Sarah Chen
  Jordan Kim (Director of Ops at GrowthCo) → DM to Mike Johnson
 
Done. Sent 2 alerts.

# Check for demo bookings every 15 minutes
*/15 * * * * cd /path/to/your/project && claude -p "Run /demo-alerts" --allowedTools 'Bash(*)' 'Read(*)'

name: Demo Alerts
on:
  schedule:
    - cron: '*/15 * * * *'  # Every 15 minutes
  workflow_dispatch: {}      # Manual trigger for testing
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /demo-alerts"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          HUBSPOT_PORTAL_ID: ${{ secrets.HUBSPOT_PORTAL_ID }}