# Clawdbot Integration Guide

## Overview

Clawdbot is a Telegram bot that provides conversational access to the RateRight Growth Engine. This document explains how Clawdbot integrates with the Growth Engine API and what capabilities it has.

---

## Architecture

```
Telegram User → Clawdbot Bot → Growth Engine API → Supabase
                    ↓
            Growth Engine Skill (~/clawd/skills/growth-engine/)
```

**Key Components:**
- **Clawdbot Server:** VPS at 134.199.153.159
- **Growth Engine API:** https://rateright-growth-production.up.railway.app
- **Clawdbot Config:** `~/.clawdbot/.env`
- **Skills Directory:** `~/clawd/skills/`

---

## Authentication

Clawdbot uses API key authentication to access the Growth Engine:

**Header:** `X-API-Key: [CLAWDBOT_API_KEY]`

**Implemented in:** `src/middleware/apiKey.js`

```javascript
// Clawdbot is recognized as a system user
if (apiKey === CLAWDBOT_API_KEY) {
  req.user = {
    id: 'clawdbot',
    email: 'clawdbot@system',
    displayName: 'Clawdbot'
  };
  return next();
}
```

---

## Available Endpoints

### 1. Call List Intelligence

**Get Next Best Call**
```bash
GET /api/call-list
```

Returns prioritized call list with:
- Pattern boosting (winning patterns get 1.5x priority)
- Score-based ranking (Hot → Warm → Cool → Cold)
- Last contact timing
- AI-generated call notes

**Response:**
```json
{
  "calls": [
    {
      "id": "uuid",
      "name": "John Smith",
      "phone": "+61412345678",
      "trade": "Electrician",
      "score": 85,
      "priority": 1.5,
      "lastContact": "2026-01-25T10:30:00Z",
      "notes": "Follow up on quote discussion",
      "pattern_boost": true
    }
  ]
}
```

### 2. Lead Management

**Get Lead Details**
```bash
GET /api/leads/:id
```

**Search Leads**
```bash
GET /api/leads?search=John&status=active
```

**Update Lead**
```bash
PATCH /api/leads/:id
Content-Type: application/json

{
  "status": "contacted",
  "notes": "Great conversation, sending quote"
}
```

### 3. Communications

**Send SMS**
```bash
POST /api/communications/sms
Content-Type: application/json

{
  "leadId": "uuid",
  "message": "Hi John, following up on our chat..."
}
```

**Get Recent Messages**
```bash
GET /api/communications?leadId=uuid&type=sms&limit=10
```

### 4. AI Tools

**Generate Intel Brief**
```bash
POST /api/ai/intel-brief
Content-Type: application/json

{
  "leadId": "uuid"
}
```

Returns pre-call preparation with similar wins.

**Draft SMS**
```bash
POST /api/ai/draft-message
Content-Type: application/json

{
  "leadId": "uuid",
  "context": "Follow up after quote sent"
}
```

**Get AI Suggestion**
```bash
POST /api/ai/suggest
Content-Type: application/json

{
  "leadId": "uuid",
  "transcript": "I'm not sure about the price...",
  "context": "objection_handling"
}
```

### 5. Job Triggers

**Run Weekly Report**
```bash
POST /api/jobs/weeklyReport
```

**Run Platform Sync**
```bash
POST /api/sync/platform/recent
```

**Check System Health**
```bash
GET /api/jobs/audit-latest
```

### 6. Analytics

**Get Rep Performance**
```bash
GET /api/jobs/rep-performance?weeks=1
```

**Get Call Scores**
```bash
GET /api/jobs/call-scores/:userId?days=7
```

**Get Audit History**
```bash
GET /api/jobs/audit-history?days=7&type=critical
```

---

## Example Curl Commands

```bash
# Get next person to call
curl -X GET \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  https://rateright-growth-production.up.railway.app/api/call-list

# Get lead details
curl -X GET \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  https://rateright-growth-production.up.railway.app/api/leads/abc-123

# Send SMS
curl -X POST \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leadId":"abc-123","message":"Hi!"}' \
  https://rateright-growth-production.up.railway.app/api/communications/sms

# Generate intel brief
curl -X POST \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leadId":"abc-123"}' \
  https://rateright-growth-production.up.railway.app/api/ai/intel-brief

# Check system health
curl -X GET \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  https://rateright-growth-production.up.railway.app/api/jobs/audit-latest

# Trigger weekly report
curl -X POST \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  https://rateright-growth-production.up.railway.app/api/jobs/weeklyReport
```

---

## Clawdbot Server Setup

### Directory Structure

```
~/.clawdbot/
  └── .env                           # API keys and config

~/clawd/
  ├── skills/
  │   └── growth-engine/
  │       └── SKILL.md               # Growth Engine skill definition
  └── gateway/                       # Clawdbot gateway service
```

### Environment Variables

**File:** `~/.clawdbot/.env`

```bash
# Growth Engine API
GROWTH_ENGINE_API_URL=https://rateright-growth-production.up.railway.app
CLAWDBOT_API_KEY=your-api-key-here

# Telegram Bot (if not already set)
TELEGRAM_BOT_TOKEN=your-bot-token
```

### Growth Engine Skill

**File:** `~/clawd/skills/growth-engine/SKILL.md`

This skill provides natural language access to Growth Engine features:
- "Who should I call next?" → GET /api/call-list
- "Show me John Smith's details" → GET /api/leads?search=John
- "Send SMS to lead 123" → POST /api/communications/sms
- "Generate intel brief for lead 456" → POST /api/ai/intel-brief
- "What's the system health?" → GET /api/jobs/audit-latest
- "Run the weekly report" → POST /api/jobs/weeklyReport

See skill implementation in `~/clawd/skills/growth-engine/SKILL.md` for full details.

---

## Security Considerations

### API Key Management

1. **Production API Key:** Store in `~/.clawdbot/.env`, never commit to Git
2. **Key Rotation:** Change `CLAWDBOT_API_KEY` in both Railway and Clawdbot server if compromised
3. **Scope:** Clawdbot has full API access (same as authenticated users)

### Rate Limiting

- Slack notifications: Max 1/second (throttled in `src/services/slack.js`)
- AI endpoints: No hard limit (uses OpenAI rate limits)
- Database queries: No hard limit (uses Supabase connection pooling)

**Recommendation:** Add rate limiting to Clawdbot skill if exposed to many users.

### Audit Trail

All Clawdbot actions are logged as user `clawdbot`:
- SMS sent by Clawdbot show `sent_by: 'clawdbot'`
- Communications show `user_id: 'clawdbot'`
- Audit logs track Clawdbot API calls

---

## Deployment Checklist

### Initial Setup

- [ ] SSH access to 134.199.153.159
- [ ] `~/.clawdbot/.env` created with `CLAWDBOT_API_KEY`
- [ ] `~/clawd/skills/growth-engine/SKILL.md` created
- [ ] Gateway restarted
- [ ] Test: "Who should I call next?" in Telegram

### Environment Variables (Railway)

Ensure these are set in Railway dashboard:

- [ ] `CLAWDBOT_API_KEY` (matches `~/.clawdbot/.env`)
- [ ] `INTERNAL_JOB_KEY` (NEW - no longer has fallback)
- [ ] `SLACK_WEBHOOK_URL`
- [ ] `OPENAI_API_KEY`
- [ ] `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`
- [ ] `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`

### Verification

```bash
# 1. Test API access from Clawdbot server
ssh root@134.199.153.159
curl -X GET \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  https://rateright-growth-production.up.railway.app/api/call-list

# 2. Test Telegram bot
# Send message: "Who should I call next?"
# Expected: List of leads with names, trades, scores

# 3. Check Railway logs
# Should see: [API] Clawdbot request: GET /api/call-list
```

---

## Troubleshooting

### "Invalid API key" Error

**Cause:** API key mismatch between Railway and Clawdbot server

**Fix:**
1. Check Railway env var: `CLAWDBOT_API_KEY`
2. Check Clawdbot server: `cat ~/.clawdbot/.env | grep CLAWDBOT_API_KEY`
3. Ensure they match exactly
4. Restart gateway: `cd ~/clawd/gateway && pm2 restart all`

### "Internal job endpoint is disabled" Error

**Cause:** `INTERNAL_JOB_KEY` not set in Railway (security fix applied)

**Fix:**
1. Go to Railway dashboard → Environment Variables
2. Add: `INTERNAL_JOB_KEY=your-secure-random-key-here`
3. Use this key for internal job triggers (not Clawdbot - Clawdbot uses `X-API-Key`)

### "No response from bot"

**Cause:** Gateway not running or skill not loaded

**Fix:**
1. SSH to Clawdbot server: `ssh root@134.199.153.159`
2. Check gateway: `pm2 status`
3. Check logs: `pm2 logs gateway`
4. Restart: `pm2 restart gateway`

### "Growth Engine API timeout"

**Cause:** Railway app sleeping or database issue

**Fix:**
1. Check Railway dashboard for app status
2. Check Supabase dashboard for connection issues
3. Check logs: Railway → Deployments → View Logs

---

## Monitoring & Observability

### Railway Logs

**Filter for Clawdbot activity:**
```
[API] Clawdbot request: GET /api/call-list
[AI] Generating intel brief for lead abc-123 (requested by clawdbot)
[SMS] Message sent to +61412345678 (sent by clawdbot)
```

### Slack Notifications

Clawdbot-triggered events appear in Slack:
- Weekly reports (if triggered manually)
- System health alerts
- Critical audit failures

### Database Queries

```sql
-- Recent Clawdbot activity
SELECT * FROM communications
WHERE metadata->>'sent_by' = 'clawdbot'
ORDER BY created_at DESC
LIMIT 20;

-- Clawdbot SMS volume
SELECT COUNT(*) as sms_count, DATE(created_at) as date
FROM communications
WHERE type = 'sms'
  AND direction = 'outbound'
  AND metadata->>'sent_by' = 'clawdbot'
GROUP BY DATE(created_at)
ORDER BY date DESC;
```

---

## Common Use Cases

### 1. Daily Call List

**User:** "Who should I call today?"

**Clawdbot:**
1. GET /api/call-list
2. Parse top 5 leads
3. Format as readable message with names, trades, scores
4. Include "why" reasoning (pattern boost, last contact, score tier)

### 2. Quick SMS

**User:** "Send SMS to John: 'Thanks for chatting, here's the quote...'"

**Clawdbot:**
1. Search leads: GET /api/leads?search=John
2. If multiple matches, ask for disambiguation
3. Send SMS: POST /api/communications/sms
4. Confirm: "SMS sent to John Smith (+61412345678)"

### 3. Pre-Call Intel

**User:** "I'm about to call lead 456, what should I know?"

**Clawdbot:**
1. GET /api/leads/456
2. POST /api/ai/intel-brief (leadId: 456)
3. Format intel brief with:
   - Lead background
   - Similar wins
   - Objection responses
   - Suggested talking points

### 4. System Health Check

**User:** "How's the system doing?"

**Clawdbot:**
1. GET /api/jobs/audit-latest
2. GET /api/jobs/audit-history?days=1
3. Format health report:
   - Current score (0-100)
   - Passed/failed checks
   - Trend (improving/declining/stable)
   - Critical issues (if any)

### 5. Weekly Insights

**User:** "What's working this week?"

**Clawdbot:**
1. POST /api/jobs/weeklyReport
2. Wait for completion
3. Summarize key findings:
   - Best trades
   - Best contact times
   - Winning channels
   - Effective objection responses

---

## API Response Formats

### Call List Response

```json
{
  "calls": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Smith",
      "phone": "+61412345678",
      "trade": "Electrician",
      "source": "RateRight Platform",
      "score": 85,
      "tier": "hot",
      "priority": 1.5,
      "lastContact": "2026-01-20T14:30:00.000Z",
      "lastContactType": "call",
      "daysSinceContact": 7,
      "notes": "Interested in commercial work. Quote sent last week.",
      "pattern_boost": true,
      "pattern_reason": "Electricians contacted on Tue 2pm have 45% conversion rate"
    }
  ],
  "total": 42,
  "filters": {
    "minScore": 20,
    "excludeCold": false
  }
}
```

### Lead Details Response

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Smith",
  "email": "john@example.com",
  "phone": "+61412345678",
  "trade": "Electrician",
  "source": "RateRight Platform",
  "status": "active",
  "score": 85,
  "tier": "hot",
  "notes": "Interested in commercial work",
  "created_at": "2026-01-15T10:00:00.000Z",
  "updated_at": "2026-01-25T16:30:00.000Z",
  "metadata": {
    "platform_id": "12345",
    "activation_stage": "active_contractor",
    "conversion_probability": 0.78
  },
  "recent_communications": [
    {
      "id": "comm-123",
      "type": "call",
      "direction": "outbound",
      "created_at": "2026-01-20T14:30:00.000Z",
      "summary": "Great conversation about upcoming commercial projects"
    }
  ]
}
```

### AI Intel Brief Response

```json
{
  "brief": "# Pre-Call Intel: John Smith\n\n## Background\n- Trade: Electrician\n- Source: RateRight Platform\n- Score: 85 (Hot)\n- Last Contact: 7 days ago (call)\n\n## Similar Wins\n3 recent Electrician conversions:\n- Mike Jones (Score 82) → Converted after 2 calls\n- Sarah Brown (Score 88) → Converted after follow-up quote\n- Tom Davis (Score 75) → Converted via SMS\n\n## Key Talking Points\n- Focus on commercial opportunities\n- Mention our fast turnaround times\n- Highlight success stories from other electricians\n\n## Common Objections & Responses\n- \"Too busy\" → Focus on quality over quantity\n- \"Price concerns\" → Break down value proposition\n- \"Already have leads\" → Emphasize our pre-qualified leads\n\n## Suggested Opening\n\"Hi John, following up on our chat last week. I've got some great commercial opportunities that match what you're looking for...\"",
  "leadId": "550e8400-e29b-41d4-a716-446655440000",
  "generatedAt": "2026-01-27T12:00:00.000Z"
}
```

### System Health Response

```json
{
  "audit": {
    "id": "audit-789",
    "score": 95,
    "passed": 18,
    "failed": 1,
    "warnings": 2,
    "audit_type": "critical",
    "created_at": "2026-01-27T11:45:00.000Z",
    "checks": {
      "database": { "status": "pass", "latency_ms": 12 },
      "api": { "status": "pass", "response_time_ms": 150 },
      "twilio": { "status": "pass" },
      "openai": { "status": "pass" },
      "slack": { "status": "warning", "message": "Near rate limit" },
      "platform_sync": { "status": "fail", "message": "Last sync 2 hours ago" }
    }
  },
  "trend": "stable",
  "summary": "System healthy. 1 failed check: Platform sync delayed."
}
```

---

## Extending Clawdbot Capabilities

### Adding New Commands

1. **Identify API endpoint** - What Growth Engine API does this need?
2. **Update skill definition** - Add command pattern to `SKILL.md`
3. **Test with curl** - Verify API returns expected data
4. **Test in Telegram** - Send command to bot
5. **Document** - Add to this guide

### Example: Add "Show my stats" Command

**API endpoint:** `GET /api/jobs/rep-performance?weeks=1`

**Skill pattern:**
```markdown
If user asks about personal stats/performance:
- GET /api/jobs/rep-performance?weeks=1
- Filter for current user (if auth implemented)
- Format as readable summary
```

**Test:**
```bash
curl -X GET \
  -H "X-API-Key: $CLAWDBOT_API_KEY" \
  https://rateright-growth-production.up.railway.app/api/jobs/rep-performance?weeks=1
```

**Expected result:** User asks "Show my stats", bot replies with calls, conversions, conversion rate, coaching tips.

---

## Maintenance

### Monthly Tasks

- [ ] Rotate `CLAWDBOT_API_KEY` (optional, if security policy requires)
- [ ] Review Clawdbot logs for errors or abuse
- [ ] Check Railway usage (API calls, bandwidth)
- [ ] Update skill definition with new API endpoints

### When API Changes

1. Update this doc (`docs/CLAWDBOT-INTEGRATION.md`)
2. Update skill definition (`~/clawd/skills/growth-engine/SKILL.md`)
3. Test all commands in Telegram
4. Notify Clawdbot users of new features

### Monitoring Queries

```sql
-- Clawdbot usage by endpoint
SELECT
  metadata->>'endpoint' as endpoint,
  COUNT(*) as request_count,
  DATE(created_at) as date
FROM api_logs
WHERE user_id = 'clawdbot'
GROUP BY endpoint, DATE(created_at)
ORDER BY date DESC, request_count DESC;

-- Clawdbot-sent SMS performance
SELECT
  COUNT(*) as total_sent,
  COUNT(CASE WHEN metadata->>'intent' = 'positive' THEN 1 END) as positive_responses,
  ROUND(
    COUNT(CASE WHEN metadata->>'intent' = 'positive' THEN 1 END)::numeric /
    NULLIF(COUNT(*), 0) * 100,
    1
  ) as response_rate_pct
FROM communications
WHERE metadata->>'sent_by' = 'clawdbot'
  AND type = 'sms'
  AND direction = 'outbound'
  AND created_at >= NOW() - INTERVAL '7 days';
```

---

## Support & Contact

**Issues with Clawdbot Integration:**
- Check Railway logs: https://railway.app → rateright-growth-production → Deployments
- Check Clawdbot logs: `ssh root@134.199.153.159` → `pm2 logs gateway`
- Review this doc: `docs/CLAWDBOT-INTEGRATION.md`

**API Questions:**
- See main docs: `CLAUDE.md`, `docs/CODEBASE_MAP.md`
- See API routes: `src/routes/*.js`

**Feature Requests:**
- Add to `docs/ROADMAP.md`
- Update `docs/SYSTEM-INTEL.md` priority queue

---

## Changelog

### 2026-01-27
- Initial Clawdbot integration documentation
- Added API key authentication
- Fixed `INTERNAL_JOB_KEY` security issue (removed hardcoded fallback)
- Documented all available endpoints
- Added troubleshooting guide

---

## See Also

- `CLAUDE.md` - Project overview and patterns
- `docs/CODEBASE_MAP.md` - Complete architecture map
- `docs/SYSTEM-INTEL.md` - Feature status and priorities
- `BUILD-GUIDE.md` - Build history and changelog
- `src/middleware/apiKey.js` - Authentication implementation
- `src/routes/*.js` - All API endpoints