Skip to main content

​
What HubSpot adds to Halo

HubSpot is Halo’s most capable integration — it does ingest, actions, and notifications:
ModeWhat it does
IngestContacts, companies, deals, and engagements (emails, notes, calls, meetings, form submissions) sync into Halo. Engagement bodies become searchable knowledge.
ActionsAgents can create deals, update contact properties, log follow-up tasks, and attach free-form notes.
NotificationsSlack notifications fire on new HubSpot engagements (when both Slack and HubSpot notifications are enabled).
Connect at Integrations > HubSpot.

​
Setup

​
Connecting

Click Connect HubSpot. You’ll be redirected to HubSpot’s OAuth consent screen. The required scopes:
  • crm.objects.contacts.read and crm.objects.contacts.write
  • crm.objects.companies.read
  • crm.objects.deals.read and crm.objects.deals.write
  • sales-email-read
  • forms
After approval, Halo encrypts and stores your tokens, fires off a full historical sync (contacts → companies → deals → engagements), and populates your knowledge base. For real-time engagement updates, configure HubSpot webhooks pointing at: 
https://app.haloagents.ai/api/integrations/hubspot/webhook/{orgId}
(Find your orgId in Setup > Deploy.) Halo verifies HubSpot’s v2 signature on every webhook payload and processes:
  • email.creation
  • note.creation
  • call.creation
  • meeting.creation
Without webhooks, you still get hourly cron syncs (HubSpot has cronSync: true).

​
Ingest mode

When ingest is on, Halo syncs:
DataWhere it lands
Contactsend_users table, linked to companies by HubSpot association
Companiescompanies table, with industry/employee count/lifecycle stage
DealsInternal deal records, accessible via segments
Engagementshubspot_engagements table + indexed in your knowledge base under the hubspot: prefix
Engagement bodies are distillable — Halo can run an additional summarization pass to extract per-customer insights (“This customer prefers monthly invoices, account manager is Sarah, renewal in March”).

​
Sync behavior

  • First connect: full backfill of all data
  • Cron: hourly incremental sync (when last_synced is set and ingest is on)
  • Webhooks: real-time engagement events
  • Manual sync: button on the integration detail page; supports full_resync, catch_up, email_catch_up, and backfill_transcripts options

​
AI actions

Four actions enable on a per-agent basis at AI Agents > [Agent] > Actions:

​
create_deal

Opens a new HubSpot deal for the conversation’s contact. Use when the user expresses buying intent or asks for a quote. Configuration: default pipeline, default stage, default owner, default deal type. The action associates the deal with the matched contact when an email match is found.

​
update_contact

Patches a single property on the contact. Use sparingly — only properties you’ve allowlisted can be modified. Configuration: allowed_properties list. Defaults: lifecyclestage, hs_lead_status, jobtitle, phone. The agent must confirm the change with the user before invoking.

​
log_activity

Creates a follow-up task on the contact in HubSpot. Use for “send pricing PDF tomorrow” or “call back about renewal.” Configuration: task type (TODO / CALL / EMAIL), priority, default due date offset.

​
create_note

Attaches a free-form note to the contact in HubSpot. Use for handoff context, customer preferences, or AI summaries of conversations. Configuration: optional body_prefix prepended to every note (e.g. “Halo AI summary:”).

​
Notifications mode

When HubSpot notifications mode is on AND Slack is connected with the new_hubspot_engagement notification type enabled, Halo posts a Slack message every time a HubSpot engagement is processed. The notification includes:
  • The engagement type (email, note, call, meeting)
  • The contact name and company
  • A snippet of the body
  • A link to the engagement in HubSpot
Use this when you want your team to see HubSpot activity in real time without checking HubSpot itself.

​
Stats and status

The integration page shows:
  • Total contacts, companies, deals, engagements synced
  • Linked engagements (those associated with known Halo contacts)
  • Last sync time
  • Auth error or sync error banners when applicable

​
Disconnecting

Click Disconnect on the integration page to remove access. All ingested data stays in Halo but no further sync happens. Reconnecting performs a fresh OAuth flow and triggers a new full sync.

​
Where to go next

Agent Actions

Enable HubSpot actions per agent.

Slack

Set up Slack to receive HubSpot engagement notifications.

Learning Rules

Filter what gets learned from HubSpot engagement bodies.