Set up HubSpot integration
The HubSpot integration sends contact details collected by your AI Agent directly to your HubSpot CRM. When a visitor shares their name, email address, or phone number, a new contact is automatically created or an existing contact is updated. No manual data entry, no CSV files.
In short
Heyloha connects to HubSpot via a Private App. Contact data is mapped directly to standard HubSpot contact properties. Existing contacts are automatically updated based on email address.
What gets synchronized?
All contact fields you select in Heyloha are automatically sent to standard HubSpot contact properties. No custom field configuration is needed.
- First name and last name
- Email address
- Phone number
- Address, zip code, city, and country
Heyloha uses HubSpot's upsert endpoint: if a contact with the same email address already exists, the information is updated instead of creating a duplicate.
What do you need?
- A HubSpot account with API access (available on all paid and free CRM plans).
- A Private App in HubSpot with the correct permissions.
- An active Heyloha account with at least one AI Agent.
Create a Private App in HubSpot
Go to Private Apps
Log in to HubSpot and go to Settings > Integrations > Private Apps.
Create a new Private App
Click 'Create a Private App' and give it a recognizable name, for example 'Heyloha'.
Set the correct permissions
Go to the 'Scopes' tab and enable these two permissions: crm.objects.contacts.write and crm.objects.contacts.read.
Copy the Access Token
After creating the app, an Access Token appears. Copy it; you'll need it in Heyloha.
Keep the Access Token secure. Don't share it with third parties. In Heyloha, the token is stored encrypted and never shown in logs.
Set up the integration in Heyloha
Open your AI Agent
Go to the Heyloha dashboard and click the AI Agent you want to connect.
Settings > Advanced > Integrations
Click 'Add integration' to create a new connection.
Choose 'HubSpot' as platform
Select HubSpot from the list. The form adapts automatically and shows only the fields you need.
Paste the Access Token
Paste the Private App Access Token you copied from HubSpot. No URL is needed; Heyloha connects directly to the HubSpot API.
Name the integration
Choose a recognizable name, for example 'HubSpot Lead Sync'. This name is also used as an internal function name.
Select contact fields
Choose which data your AI Agent should collect. Select at least an email address. The AI only asks for the fields you select here.
Choose event triggers
Select when the integration should fire: when contact details are captured, when an appointment is booked, or when a goal is reached.
Describe when to use the integration
Provide a short instruction for when the AI should trigger this integration, for example: 'Use this when a visitor wants to schedule a demo and shares their details.'
Save and activate
Set the integration to 'Active' and click Save. Don't forget to also save the AI Agent itself.
Test the connection
After saving, you can test the connection directly using the 'Test connection' button on the integration card. A test contact is sent to HubSpot.
- Green 'Connected': your credentials are valid and HubSpot accepted the test contact.
- Red error: something is wrong. The error message indicates what went wrong (invalid token, missing permissions, etc.).
Check your HubSpot contacts after testing. You should see a test contact named 'Test Contact' with the email address test@heyloha.ai.
HubSpot Notes with chat transcript
When you enable "Include transcript", Heyloha automatically creates a Note on the HubSpot contact with a summary of the chat conversation. This gives your sales team immediate context about what the visitor was interested in.
Delivery log
Every dispatch attempt is recorded in the delivery log, accessible from the integration card. The log shows the timestamp, event, status (succeeded, failed, or retrying), and number of attempts. Account managers can view the full request and response data for debugging.
Heyloha retries every dispatch up to 4 times (1 inline attempt + 3 async retries with exponential backoff). A brief HubSpot outage won't result in lost leads.
Frequently asked questions
Which HubSpot plan do I need?
You need a HubSpot plan with API access and the crm.objects.contacts.write scope. This is available on all paid CRM plans and the free CRM plan. Note: developer test accounts may not have this scope available. Use a free CRM account or a paid plan.
Are duplicates prevented?
Yes. Heyloha uses HubSpot's upsert endpoint. If a contact with the same email already exists, the data is updated instead of creating a new contact.
Can I combine HubSpot with other integrations?
Yes. Each AI Agent can have multiple integrations. For example, you can send to both HubSpot and ActiveCampaign simultaneously.
Set up generic webhook integrationSet up ActiveCampaign integration