Connect to HubSpot CRM using OAuth 2.0
Prerequisites
Before you begin, ensure you have:- A HubSpot account with CRM access
- Admin or super admin permissions in HubSpot
- Organization admin access in Ravenna
Required permissions
The HubSpot integration requires the following OAuth scopes:| Scope | Purpose |
|---|---|
crm.objects.deals.read | Access deal data |
crm.objects.companies.read | Access company data |
crm.objects.contacts.read | Access contact data |
crm.objects.owners.read | Access owner/user data |
crm.objects.users.read | Access user information |
crm.schemas.deals.read | Read deal property definitions |
crm.schemas.companies.read | Read company property definitions |
crm.schemas.contacts.read | Read contact property definitions |
settings.users.read | Read user settings |
settings.users.teams.read | Read team information |
These are read-only permissions. Ravenna does not create, modify, or delete any data in your HubSpot account.
Setup guide
1
Navigate to integrations
- Go to Settings > Integrations
- Find HubSpot in the CRM section
2
Start OAuth flow
Click Connect with HubSpot to begin the authorization process.You’ll be redirected to HubSpot to authorize the connection.
3
Authorize access
- Sign in to HubSpot if prompted
- Select the HubSpot account you want to connect
- Review the requested permissions
- Click Connect app to authorize Ravenna
4
Complete setup
After authorization, you’ll be redirected back to Ravenna. The integration will:
- Validate the OAuth tokens
- Fetch your HubSpot portal information
- Enable HubSpot agent tools
Enable agent tools
After connecting HubSpot, enable the tools on your AI agents:1
Navigate to agent settings
Go to Settings > AI > Agents or your workspace agent configuration.
2
Enable HubSpot tools
Toggle on the HubSpot tools you want your agent to use:
- List Deals - For browsing recent deals
- Search Deals - For filtered deal queries
- Get Deal - For detailed deal information
- Search Companies - For company lookups
- List Owners - For owner/user lookups
- Search Contacts - For contact lookups
3
Test the integration
Try asking your agent questions like:
- “Show me recent deals”
- “What are our high priority deals?”
- “Find deals for ABC Company”
- “Who owns the XYZ deal?”
Troubleshooting
OAuth authorization failed
OAuth authorization failed
Insufficient permissions
Insufficient permissions
Cause: Your HubSpot user doesn’t have access to required CRM dataSolution:
- Verify you have CRM access in your HubSpot account
- Check with your HubSpot admin about user permissions
- Ensure the connected portal has the required HubSpot subscription tier
No deals found
No deals found
Cause: The search returned no resultsSolution:
- Verify deals exist in your HubSpot account
- Check that the search filters match existing data
- Try broader search criteria
- Ensure the connected HubSpot portal is the correct one
Company associations missing
Company associations missing
Cause: Deals don’t have associated companies in HubSpotSolution:
- Associate companies with deals in HubSpot
- Check that company records exist in your HubSpot account
- Verify associations are set up correctly in HubSpot
Token expired error
Token expired error
Cause: OAuth access token has expiredSolution:
- Ravenna automatically refreshes tokens, but if issues persist:
- Disconnect and reconnect the HubSpot integration
- Check that your HubSpot account is still active
Data access
Ravenna accesses HubSpot data in real-time. There is no data sync or storage of your CRM data in Ravenna.
- The query is sent to HubSpot’s API
- Results are returned and formatted for the agent
- The agent uses the data to answer the user’s question
- No CRM data is stored in Ravenna
Features
Once connected, your agents can answer CRM-related questions:Pipeline visibility
“What deals are in negotiation stage?”
Priority tracking
“Show me high priority open deals”
Company insights
“What deals do we have with Acme Corp?”
Owner workload
“What deals does [email protected] own?”