HubSpot Integration

The HubSpot integration connects your AI voice agents to your HubSpot CRM. Calls are logged as engagements, contacts are created or updated automatically, and your post-call workflows can manage deals and book meetings.

Prerequisites

• A HubSpot account with CRM access
• A BuildVoiceAI account on the Growth or Agency plan

Connecting HubSpot

HubSpot uses OAuth exclusively for authentication.

1. Navigate to Integrations in the sidebar
2. Find the HubSpot card and click Connect
3. You will be redirected to HubSpot’s authorization page
4. Review the permissions BuildVoiceAI is requesting
5. Click Grant Access
6. You will be redirected back to BuildVoiceAI with the connection confirmed

Required HubSpot Scopes

During authorization, BuildVoiceAI requests the following scopes:

• crm.objects.contacts.read and crm.objects.contacts.write — Read and create/update contacts
• crm.objects.deals.read and crm.objects.deals.write — Read and manage deals
• crm.schemas.contacts.read — Read contact properties including custom fields
• sales-email-read — Read engagements
• timeline — Create timeline events

If your HubSpot account restricts any of these scopes, certain features will not work.

Configuration

Default Agent

Select which agent handles calls triggered from HubSpot webhooks.

1. On the HubSpot integration page, find Default Agent
2. Select an agent from the dropdown
3. Click Save

Webhook URL for Triggered Calls

To trigger outbound calls from HubSpot workflows:

1. Copy the Webhook URL from the HubSpot integration page in BuildVoiceAI
2. In HubSpot, navigate to Automations → Workflows
3. Create a new workflow or edit an existing one
4. Add a Send a webhook action
5. Set the method to POST and paste the BuildVoiceAI webhook URL
6. Include the contact’s phone number in the request body

Features

Call Engagements

Every completed call is logged as a call engagement on the matching HubSpot contact. The engagement includes:

• Call direction and duration
• AI-generated call summary
• Sentiment analysis
• Full transcript (stored as a note)

BuildVoiceAI uses HubSpot’s association system to link records. The relevant association type IDs are:

Contact Management

Post-call workflows can create new HubSpot contacts or update existing ones:

• Search by phone — BuildVoiceAI matches callers to existing contacts by phone number
• Create contacts — If no match is found, a new contact is created with the caller’s details
• Update properties — Custom and standard properties can be updated based on call data

Contact Tagging

HubSpot does not have a native tagging system for contacts. BuildVoiceAI uses a custom contact property called ai_call_tags to provide tag-like functionality.

• Tags are stored as a semicolon-separated string (e.g., interested;follow-up;demo-requested)
• When adding tags through a workflow action, BuildVoiceAI fetches the existing tags, merges the new ones, and writes the combined list back
• This prevents overwriting tags set by previous calls or other processes

Deal Pipeline Updates

Workflow actions can create or update deals associated with a contact. You can:

• Create a new deal when a call meets certain criteria
• Move a deal to a different pipeline stage based on call outcome
• Update deal properties (amount, close date, etc.)

Meeting Bookings

If your voice agent collects scheduling information during a call, a workflow action can create a meeting engagement in HubSpot linked to the contact.

Troubleshooting

”Token Expired” or Authorization Errors

HubSpot OAuth tokens expire periodically. BuildVoiceAI refreshes them automatically, but if you see persistent auth errors:

1. Go to Integrations → HubSpot
2. Click Disconnect
3. Click Connect to re-authorize
4. Grant access again in HubSpot

Contacts Not Being Found

If calls are creating duplicate contacts instead of matching existing ones:

• Verify the caller’s phone number format matches what is stored in HubSpot
• Phone numbers should be in E.164 format (e.g., +15551234567)
• Check that the phone property is populated on the HubSpot contact

Tags Not Appearing

If ai_call_tags values are missing or being overwritten:

• Confirm the ai_call_tags custom property exists on your HubSpot contacts
• Check that your workflow action is set to merge tags, not replace them
• Review the workflow execution log for errors

Webhook Not Triggering Calls

• Verify the webhook URL is current (copy it fresh from the integration page)
• Ensure the HubSpot workflow is enrolled and active
• Confirm the payload includes a valid phone number
• Check that the default agent is set in the integration configuration