whoop-integration

name	whoop-integration
description	Integrate with WHOOP fitness tracker API to monitor sleep, recovery, and strain data. Use when you need to check sleep quality, recovery scores, analyze fitness patterns, set up morning behavior adjustments based on sleep performance, or create automated health monitoring workflows. Supports OAuth authentication, sleep performance tracking, and adaptive assistant behavior.
metadata	{"openclaw":{"emoji":"🏃‍♀️","requires":{"env":["WHOOP_CLIENT_ID","WHOOP_CLIENT_SECRET"]},"primaryEnv":"WHOOP_CLIENT_SECRET"}}

WHOOP Integration

Monitor sleep, recovery, and strain data from WHOOP fitness tracker.

Tokens

Tokens stored in ~/.openclaw/whoop_tokens.json:

{
  "access_token": "...",
  "refresh_token": "...",
  "obtained_at": "ISO timestamp",
  "expires_at": "ISO timestamp"
}

Token Rotation

Refresh endpoint (IMPORTANT — other paths return 404!):

POST https://api.prod.whoop.com/oauth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

CLIENT_ID and CLIENT_SECRET are in env vars WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET.

Rotate when expires_at is within 1 hour. Save new tokens with obtained_at and expires_at.

API Endpoints

Base URL: https://api.prod.whoop.com/developer Auth: Authorization: Bearer {access_token}

⚠️ Use V2 endpoints! V1 returns 404!

Sleep

GET /v2/activity/sleep?limit=1

Key fields in records[0].score:

• sleep_performance_percentage — overall quality (0-100%)
• sleep_efficiency_percentage — time asleep vs in bed
• sleep_consistency_percentage
• respiratory_rate
• stage_summary:
  • total_in_bed_time_milli
  • total_light_sleep_time_milli
  • total_slow_wave_sleep_time_milli (deep sleep)
  • total_rem_sleep_time_milli
  • total_awake_time_milli
  • sleep_cycle_count
  • disturbance_count

Recovery

GET /v2/recovery?limit=1

Key fields in records[0].score:

• recovery_score (0-100)
• resting_heart_rate (bpm)
• hrv_rmssd_milli (ms, higher = better)
• spo2_percentage
• skin_temp_celsius

Morning Report Format

RECOVERY FIRST — це найважливіше для користувача!

Send to Telegram (channel=telegram, target=36171288):

🏃‍♀️ WHOOP Ранковий звіт

💚 Відновлення: X% [колір]
❤️ Пульс: X bpm | HRV: X ms | SpO2: X%
📋 [Рекомендація]

😴 Сон: X% ефективність (Xг Xхв загалом)
💤 Deep: Xхв | REM: Xхв | Light: Xхв
🔄 Циклів: X | Пробуджень: X

Recovery колір та рекомендація:

• >67% (зелений 🟢): Повний газ! Можна тренуватись на максимум
• 34-67% (жовтий 🟡): Обережно, не перевантажуйся
• <34% (червоний 🔴): Відпочинок, без серйозних навантажень

Конвертація мілісекунд:

• Ділити на 60000 для хвилин
• Ділити на 3600000 для годин

Аналіз за період

Для аналізу трендів за будь-який період використовуй параметри start, end, limit.

Sleep за період

GET /v2/activity/sleep?start=2026-01-28T00:00:00.000Z&end=2026-02-04T00:00:00.000Z&limit=25

Recovery за період

GET /v2/recovery?start=2026-01-28T00:00:00.000Z&end=2026-02-04T00:00:00.000Z&limit=25

Cycles (strain) за період

GET /v2/cycle?start=2026-01-28T00:00:00.000Z&end=2026-02-04T00:00:00.000Z&limit=25

Workouts за період

GET /v2/activity/workout?start=2026-01-28T00:00:00.000Z&end=2026-02-04T00:00:00.000Z&limit=25

Дати — ISO 8601 формат. start inclusive, end exclusive. Max limit=25, для більше — пагінація через nextToken.

Що аналізувати:

• Тренди recovery — чи росте/падає відновлення за тиждень/місяць
• Середній HRV — тренд вгору = тіло адаптується, вниз = перетренованість
• Якість сну — % deep/REM від загального сну, тренд ефективності
• Strain vs Recovery — чи відповідає навантаження відновленню
• Resting HR тренд — зниження = краща форма, підвищення = стрес/хвороба
• Consistency — наскільки стабільний графік сну

Формат аналізу (Telegram):

📊 WHOOP Аналіз: [період]

💚 Recovery: avg X% (min X% — max X%) [тренд ↑↓→]
❤️ HRV: avg X ms (тренд ↑↓→)
💤 Сон: avg Xг Xхв (ефективність avg X%)
🏋️ Strain: avg X (max X)
🫀 Пульс спокою: avg X bpm (тренд ↑↓→)

📈 Висновки: [коротко що добре/погано і рекомендації]

Adaptive Behavior

Adjust communication based on recovery:

• >80%: Energetic, suggest ambitious tasks
• 67-80%: Normal, balanced approach
• 34-67%: Supportive, lighter tasks
• <34%: Gentle, minimal complexity, focus on rest