HubSpot Actions
HubSpot actions let you automatically update your HubSpot CRM after every AI call. Log call engagements, manage contacts, update deal pipelines, book meetings, and trigger HubSpot workflows.
Prerequisites
Before using HubSpot actions, you must connect your HubSpot account via OAuth:
- Go to Integrations in the sidebar
- Find HubSpot and click Connect
- Sign in to HubSpot and authorize BuildVoiceAI
The OAuth connection handles token refresh automatically. If you see authentication errors in the Execution Log, you may need to reconnect.
Available Actions
log_call
Creates a call engagement in HubSpot associated with the contact.
| Config Field | Description |
|---|---|
| (none) | Call data is automatically included (duration, direction, outcome) |
The engagement record includes call duration, direction, phone numbers, disposition, and is linked to the matching contact. HubSpot uses the association type ID 194 (Call to Contact) internally.
create_contact
Creates a new contact in HubSpot.
| Config Field | Description |
|---|---|
| (none) | Contact is created with the caller’s phone number and any available name data |
This creates a new contact every time. Use upsert_contact to prevent duplicates.
update_contact
Updates an existing contact’s properties in HubSpot. The contact is matched by phone number.
| Config Field | Description |
|---|---|
| (none) | Updates the existing contact record with latest call data |
If no matching contact is found, the action fails. Use upsert_contact if you are unsure whether the contact exists.
upsert_contact
Creates the contact if they do not exist, or updates them if they do. Matching is done by phone number.
| Config Field | Description |
|---|---|
| (none) | Looks up by phone number, creates or updates accordingly |
This is the recommended action for contact management.
add_note
Creates a note engagement on the contact’s timeline.
| Config Field | Description |
|---|---|
| Note content | The body of the note. Supports template variables like \{\{summary\}\} |
HubSpot uses association type ID 202 (Note to Contact) to link the note.
auto_tag
Adds tags to the contact using the ai_call_tags custom property.
| Config Field | Description |
|---|---|
| Tags | Tags to add to the contact |
HubSpot does not have a native tagging system like GHL. BuildVoiceAI uses a custom contact property called ai_call_tags that stores tags as a semicolon-separated string. The auto_tag action fetches the existing tags, merges the new ones, and saves the updated list. This means tags accumulate over time and are never overwritten.
update_pipeline
Moves a deal to a specific stage in a HubSpot pipeline.
| Config Field | Description |
|---|---|
| Pipeline ID | The HubSpot pipeline ID |
| Stage ID | The deal stage ID to move to |
The deal associated with the contact (via association type 3) is updated.
lead_score
Adjusts the HubSpot lead score for the contact.
| Config Field | Description |
|---|---|
| Score adjustment | Amount to add or subtract from the current score |
book_meeting
Creates a meeting engagement on the contact’s timeline.
| Config Field | Description |
|---|---|
| Title | Meeting title (supports template variables) |
| Duration | Meeting length in minutes |
| Date/Time | When to schedule the meeting |
HubSpot uses association type 200 (Meeting to Contact) to link the meeting.
cancel_meeting
Cancels an upcoming meeting associated with the contact.
| Config Field | Description |
|---|---|
| (none) | Cancels the next upcoming meeting for the contact |
trigger_workflow
Enrolls the contact in a HubSpot workflow.
| Config Field | Description |
|---|---|
| Workflow ID | The HubSpot workflow (automation) ID to enroll the contact in |
This lets you kick off HubSpot automations like email sequences, task creation, or internal notifications based on call outcomes.
HubSpot workflow enrollment uses the /automation/v4/flows/{id}/enrollments endpoint. Make sure the workflow is active in HubSpot and configured to accept API enrollments.
update_contact_property
Sets a specific property value on the contact.
| Config Field | Description |
|---|---|
| Property name | The internal name of the HubSpot contact property |
| Property value | The value to set (supports template variables) |
Use this to store call-derived data in custom HubSpot properties. For example, store \{\{sentiment\}\} in a custom “Last Call Sentiment” property.
Template Variables
All text fields support these variables, which are replaced with actual call data at execution time:
| Variable | Example Value |
|---|---|
\{\{caller_name\}\} | Jane Doe |
\{\{phone_number\}\} | +14155551234 |
\{\{summary\}\} | Caller asked about service pricing… |
\{\{sentiment\}\} | neutral |
\{\{duration\}\} | 180 |
\{\{transcript\}\} | Agent: Thanks for calling… |
Example Workflow
A typical HubSpot post-call workflow:
- upsert_contact — Ensure the caller exists in HubSpot
- log_call — Create a call engagement on their timeline
- auto_tag — Tag with
ai-calland the sentiment value - add_note — Add the AI-generated summary as a note
- update_pipeline — Move the associated deal forward
Troubleshooting
Token Refresh Errors
HubSpot refresh tokens are single-use. If you see authentication errors, it may be due to a race condition where multiple actions tried to refresh the token simultaneously. BuildVoiceAI handles this with a singleton pattern, but if issues persist, reconnect HubSpot from the Integrations page.
Missing Contact Properties
If auto_tag fails, make sure the ai_call_tags custom property exists in your HubSpot account. BuildVoiceAI creates it automatically during integration setup, but if it was deleted, you will need to recreate it as a single-line text property.