HubSpot Connect

User-facing meta-skill for HubSpot CRM integration.

Purpose

Single entry point for all HubSpot CRM operations:

• Contacts - List, create, update, search

• Companies - List, create, search

• Deals - List, create, update, search

• Associations - Get linked records

• Engagements - Emails, calls, notes, meetings

Follows the master/connect pattern - references hubspot-master for shared scripts and references.

Trigger Phrases

Load this skill when user says:

• "hubspot" / "hubspot crm"

• "list contacts" / "show contacts"

• "create contact" / "add contact"

• "search contacts" / "find contact"

• "list companies" / "show companies"

• "create company" / "add company"

• "list deals" / "show deals" / "show pipeline"

• "create deal" / "new opportunity"

• "log email" / "log call" / "add note"

• Any CRM-related query

Pre-Flight Check (ALWAYS RUN FIRST)

Before ANY HubSpot operation, validate configuration:

python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json

Handle Config Status

ai_action

What to Do

proceed_with_operation

Config OK → Continue

prompt_for_access_token

Ask user for access token, save to .env

create_env_file

Create .env with token

add_missing_scopes

Guide user to add scopes in HubSpot

verify_token

Token exists but invalid

If Setup Needed

Display this complete setup guide to user:

I need to set up HubSpot integration first.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HUBSPOT PRIVATE APP SETUP ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STEP 1: Create Private App ─────────────────────────

1. Log into HubSpot
2. Click gear icon (Settings) → Integrations → Private Apps
3. Click "Create a private app"
4. Name: "Nexus Integration"

STEP 2: Select Required Scopes ────────────────────────────── In the "Scopes" tab, enable these permissions:

CRM (Required): ☑️ crm.objects.contacts.read ☑️ crm.objects.contacts.write ☑️ crm.objects.companies.read ☑️ crm.objects.companies.write ☑️ crm.objects.deals.read ☑️ crm.objects.deals.write

Engagements (Optional - for emails/calls/notes/meetings): ☑️ crm.objects.emails.read ☑️ crm.objects.emails.write ☑️ crm.objects.calls.read ☑️ crm.objects.calls.write ☑️ crm.objects.notes.read ☑️ crm.objects.notes.write ☑️ crm.objects.meetings.read ☑️ crm.objects.meetings.write

STEP 3: Get Your Token ──────────────────────

1. Click "Create app"
2. Copy the access token shown
3. Token starts with: pat-na1-... or pat-eu1-...

⚠️ IMPORTANT: Save this token securely - you won't see it again!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Please paste your HubSpot access token:

After user provides token:

Write to .env

HUBSPOT_ACCESS_TOKEN=pat-na1-xxx

Re-run config check to verify

python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json

Handling 403 Forbidden (Missing Scopes)

If user gets 403 errors after setup, they're missing scopes:

⚠️ Missing HubSpot permissions!

The operation failed because your Private App is missing required scopes.

To fix:

1. Go to HubSpot Settings → Integrations → Private Apps
2. Click on "Nexus Integration" (or your app name)
3. Go to "Scopes" tab
4. Add the missing scope: [scope name from error]
5. Click "Commit changes"
6. IMPORTANT: Copy the NEW access token (it changes after scope updates)
7. Update your .env with the new token

Then try again!

Workflows

Workflow 0: Config Check (Auto)

Trigger: Before any operation Script: check_hubspot_config.py --json

Output: Config status, required actions

Workflow 1: List Contacts

Trigger: "list contacts", "show contacts", "get contacts"

python 00-system/skills/hubspot/hubspot-master/scripts/list_contacts.py --json

Display Format:

Found 10 contacts:

1. John Doe Email: john@example.com ID: 12345 Company: Acme Corp

2. Jane Smith Email: jane@example.com ID: 12346 ...

Workflow 2: Create Contact

Trigger: "create contact", "add contact", "new contact"

Required: Email Optional: First name, last name, phone, company

python 00-system/skills/hubspot/hubspot-master/scripts/create_contact.py
--email "user@example.com"
--firstname "John"
--lastname "Doe"
--json

Workflow 3: Search Contacts

Trigger: "search contacts", "find contact", "lookup contact"

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py
--email "john@example.com"
--json

or

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py
--name "John"
--json

Workflow 4: Update Contact

Trigger: "update contact", "edit contact", "modify contact"

Required: Contact ID

python 00-system/skills/hubspot/hubspot-master/scripts/update_contact.py
--id 12345
--phone "+1234567890"
--json

Workflow 5: List Companies

Trigger: "list companies", "show companies"

python 00-system/skills/hubspot/hubspot-master/scripts/list_companies.py --json

Workflow 6: Create Company

Trigger: "create company", "add company", "new company"

python 00-system/skills/hubspot/hubspot-master/scripts/create_company.py
--name "Acme Corp"
--domain "acme.com"
--industry "Technology"
--json

Workflow 7: Search Companies

Trigger: "search companies", "find company"

python 00-system/skills/hubspot/hubspot-master/scripts/search_companies.py
--name "Acme"
--json

Workflow 8: List Deals

Trigger: "list deals", "show deals", "show pipeline"

python 00-system/skills/hubspot/hubspot-master/scripts/list_deals.py --json

Workflow 9: Create Deal

Trigger: "create deal", "add deal", "new deal", "new opportunity"

python 00-system/skills/hubspot/hubspot-master/scripts/create_deal.py
--name "Enterprise Deal"
--amount 50000
--stage "qualifiedtobuy"
--json

Workflow 10: Update Deal

Trigger: "update deal", "edit deal", "change deal stage"

python 00-system/skills/hubspot/hubspot-master/scripts/update_deal.py
--id 12345
--stage "closedwon"
--json

Workflow 11: Search Deals

Trigger: "search deals", "find deal"

python 00-system/skills/hubspot/hubspot-master/scripts/search_deals.py
--name "Enterprise"
--min-amount 10000
--json

Workflow 12: Get Associations

Trigger: "get associations", "linked records", "related contacts", "contacts on deal"

Get contacts associated with a deal

python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py
--object-type deals
--object-id 12345
--to-type contacts
--json

Workflow 13: Engagement Operations

Trigger: Various engagement operations

List Emails:

python 00-system/skills/hubspot/hubspot-master/scripts/list_emails.py --json

Log Email:

python 00-system/skills/hubspot/hubspot-master/scripts/log_email.py
--subject "Follow up"
--body "Meeting follow-up email"
--json

List Calls:

python 00-system/skills/hubspot/hubspot-master/scripts/list_calls.py --json

Log Call:

python 00-system/skills/hubspot/hubspot-master/scripts/log_call.py
--title "Sales Call"
--body "Discussed pricing"
--duration 30
--json

List Notes:

python 00-system/skills/hubspot/hubspot-master/scripts/list_notes.py --json

Create Note:

python 00-system/skills/hubspot/hubspot-master/scripts/create_note.py
--body "Important note about this contact"
--json

List Meetings:

python 00-system/skills/hubspot/hubspot-master/scripts/list_meetings.py --json

Create Meeting:

python 00-system/skills/hubspot/hubspot-master/scripts/create_meeting.py
--title "Product Demo"
--body "Demo of new features"
--start "2025-12-15T14:00:00Z"
--end "2025-12-15T15:00:00Z"
--json

Smart Routing

When user mentions:

Phrase Route To

"list contacts", "show contacts" Workflow 1

"create contact", "add contact" Workflow 2

"search contacts", "find contact" Workflow 3

"update contact", "edit contact" Workflow 4

"list companies", "show companies" Workflow 5

"create company", "add company" Workflow 6

"search companies", "find company" Workflow 7

"list deals", "show pipeline" Workflow 8

"create deal", "new opportunity" Workflow 9

"update deal", "change stage" Workflow 10

"search deals", "find deal" Workflow 11

"associations", "linked records" Workflow 12

"emails", "calls", "notes", "meetings" Workflow 13

Error Handling

Common Errors:

Error Solution

401 Unauthorized Token invalid - check HUBSPOT_ACCESS_TOKEN

403 Forbidden Missing scope - add to Private App

404 Not Found Record doesn't exist

409 Conflict Duplicate record - search first

429 Rate Limited Wait and retry

On Error:

• Load: hubspot-master/references/error-handling.md

• Display user-friendly message

• Offer fix if possible

Context Caching

After listing records, cache for session:

Store in conversation context

contacts_cache = [ {"name": "John Doe", "id": "12345", "email": "john@example.com"}, {"name": "Jane Smith", "id": "12346", "email": "jane@example.com"} ]

When user says "update John Doe", match to cached contact ID.

Example Interactions

User: "list my hubspot contacts"

AI:

Let me check your HubSpot configuration first... ✅ Configuration valid

Found 10 contacts:

1. John Doe Email: john@example.com ID: 12345 Company: Acme Corp

2. Jane Smith Email: jane@example.com ID: 12346 Company: TechStart Inc

...

What would you like to do?

• "create contact" to add a new contact
• "search contacts by company" to filter
• "update John Doe" to modify a record

User: "create a new deal for Acme Corp worth $50,000"

AI:

Creating deal...

✅ Deal created! ID: 98765 Name: Acme Corp - $50,000 Amount: $50,000 Stage: qualifiedtobuy

Would you like to associate this deal with a contact or company?

Version

Version: 1.0 Created: 2025-12-13 Status: Production Ready