heyreach
HeyReach Integration
Complete integration for HeyReach LinkedIn automation platform.
Trigger Phrases
Load this skill when user mentions:
- "heyreach" / "heyreach campaigns"
- "linkedin outreach" / "linkedin automation"
- "list campaigns" / "show campaigns"
- "campaign stats" / "campaign metrics"
- "add leads to campaign"
- "get campaign leads"
- "linkedin accounts"
- "create lead list"
Pre-Flight Check (ALWAYS RUN FIRST)
Before ANY operation, validate configuration:
python 00-system/skills/heyreach/heyreach-master/scripts/check_heyreach_config.py --json
Handle Config Status
ai_action |
What to Do |
|---|---|
proceed_with_operation |
Config OK → Continue |
prompt_for_api_key |
Ask user for API key, save to .env |
create_env_file |
Create .env with API key |
verify_api_key |
Key exists but invalid |
If Setup Needed
I need to set up HeyReach integration first.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HEYREACH API SETUP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Log into HeyReach at https://app.heyreach.io
2. Go to Settings → API (or Integrations)
3. Copy your API key
Paste your HeyReach API key:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
After user provides key, add to .env:
HEYREACH_API_KEY=their-key-here
Scripts Reference
All scripts are in 00-system/skills/heyreach/heyreach-master/scripts/
Campaign Operations
list_campaigns.py - List all campaigns
python list_campaigns.py [--limit N] [--offset N] [--json]
Trigger: "list campaigns", "show campaigns", "my campaigns"
get_campaign.py - Get campaign details
python get_campaign.py --campaign-id ID [--json]
Trigger: "campaign details", "show campaign [name]"
toggle_campaign.py - Pause/resume campaign
python toggle_campaign.py --campaign-id ID --status ACTIVE|PAUSED [--json]
Trigger: "pause campaign", "resume campaign", "start/stop campaign"
Lead Operations
add_leads.py - Add leads to campaign
python add_leads.py --campaign-id ID --linkedin-urls URL1,URL2 [--json]
python add_leads.py --campaign-id ID --leads '[{"linkedInUrl":"..."}]' [--json]
Trigger: "add leads", "add to campaign", "import leads"
get_leads.py - Get campaign leads
python get_leads.py --campaign-id ID [--limit N] [--json]
Trigger: "campaign leads", "show leads", "list leads"
Conversation Operations
get_conversations.py - Get message threads
python get_conversations.py [--campaign-id ID] [--limit N] [--json]
Trigger: "conversations", "messages", "inbox", "replies"
LinkedIn Account Operations
list_accounts.py - List connected accounts
python list_accounts.py [--json]
Trigger: "linkedin accounts", "connected accounts", "my accounts"
List Operations
list_lists.py - List lead lists
python list_lists.py [--limit N] [--json]
Trigger: "lead lists", "show lists", "my lists"
create_list.py - Create lead list
python create_list.py --name NAME [--description DESC] [--json]
Trigger: "create list", "new list"
Analytics Operations
get_stats.py - Get overall analytics
python get_stats.py [--json]
Trigger: "heyreach stats", "overall stats", "analytics"
get_metrics.py - Get campaign metrics
python get_metrics.py --campaign-id ID [--json]
Trigger: "campaign metrics", "campaign performance"
Smart Routing Table
| User Says | Script | Required Args |
|---|---|---|
| "list campaigns" | list_campaigns.py | - |
| "campaign details [X]" | get_campaign.py | --campaign-id |
| "pause/resume [campaign]" | toggle_campaign.py | --campaign-id --status |
| "add leads to [campaign]" | add_leads.py | --campaign-id --linkedin-urls |
| "leads in [campaign]" | get_leads.py | --campaign-id |
| "conversations" | get_conversations.py | - |
| "linkedin accounts" | list_accounts.py | - |
| "lead lists" | list_lists.py | - |
| "create list [name]" | create_list.py | --name |
| "analytics/stats" | get_stats.py | - |
| "metrics for [campaign]" | get_metrics.py | --campaign-id |
Example Interactions
User: "show my heyreach campaigns"
python 00-system/skills/heyreach/heyreach-master/scripts/list_campaigns.py --json
Display:
Found 3 campaigns:
1. Q4 Enterprise Outreach
Status: ACTIVE
Leads: 350 | Contacted: 180 | Replied: 22
ID: camp-abc123
2. Startup Founders
Status: PAUSED
Leads: 200 | Contacted: 95 | Replied: 12
ID: camp-def456
User: "add linkedin.com/in/john-doe and linkedin.com/in/jane-smith to Q4 Enterprise"
python 00-system/skills/heyreach/heyreach-master/scripts/add_leads.py \
--campaign-id camp-abc123 \
--linkedin-urls "linkedin.com/in/john-doe,linkedin.com/in/jane-smith" \
--json
Display:
✅ Leads added to campaign!
Campaign ID: camp-abc123
Added: 2
User: "what are my overall stats?"
python 00-system/skills/heyreach/heyreach-master/scripts/get_stats.py --json
Display:
📊 HeyReach Analytics Overview
Total Campaigns: 5
Active Campaigns: 3
Overall Performance:
Total Leads: 1,200
Contacted: 650
Replied: 78
Rates:
Connection Rate: 45.5%
Reply Rate: 12.0%
Error Handling
| Error | Cause | Solution |
|---|---|---|
| 401 | Invalid API key | Re-run setup, get new key |
| 403 | API not available | Check subscription |
| 404 | Resource not found | Verify campaign/lead ID |
| 429 | Rate limited | Auto-retry (handled by client) |
References
- setup-guide.md - Complete setup
- api-reference.md - API docs
- error-handling.md - Troubleshooting
Version: 1.0 Created: 2025-12-19