Skip to main content

HubSpot

info

This page covers the current supported HubSpot Agent Tool integration, which connects BotDojo to HubSpot with a Private App access token.

Connect HubSpot to BotDojo so your agents can read and update CRM records directly from HubSpot.

What This Integration Supports​

The current HubSpot Agent Tool integration exposes HubSpot actions for:

  • Contacts — create, update, get, delete, list, search, and fetch recently updated contacts
  • Companies — create, update, get, delete, list, search by domain, and fetch recently updated companies
  • Deals — create, update, get, delete, list, search, and fetch recently updated deals
  • Tickets — create, update, get, delete, and list tickets
  • Associations — list associated object IDs between CRM records, such as contact to company
  • Lists — add or remove a contact from a HubSpot list
  • Engagements — create, get, delete, and list engagements
  • Meetings Scheduler — list scheduling pages, fetch booking metadata, fetch availability, and book meetings against an existing HubSpot scheduling page

Before You Start​

You will need:

  • A HubSpot account
  • Permission in HubSpot to create and manage a Private App
  • Access to BotDojo’s Integrations page
  • If you use HubSpot triggers: permission in HubSpot to configure Private App webhooks
warning

BotDojo currently validates the HubSpot connection by calling the Contacts API. Your Private App token needs contact read access or the Connect step will fail, even if you mainly want to use company, deal, or ticket actions.

Connect HubSpot In BotDojo​

  1. In HubSpot, create a Private App.
  2. Add the scopes your BotDojo agent needs.
  3. Copy the Private App access token.
  4. In BotDojo, open Integrations.
  5. In Agent Tools, find HubSpot and click Connect.
  6. Paste the token into the Access Token field.
  7. If you plan to use HubSpot triggers, also fill in:
    • Portal ID — the HubSpot account ID. You can usually see it in HubSpot URLs after /private-apps/, or in HubSpot account settings.
    • Webhook Signing Secret — the HubSpot app/client secret for the Private App that sends webhook events.
  8. Click Connect.
note

The Webhook Signing Secret is only needed for HubSpot triggers. Standard HubSpot actions only need the Private App access token and the right HubSpot scopes.

Minimum recommendation:

  • Contacts read — required for BotDojo’s connection test
  • Contacts write — if your agent will create or update contacts
  • Companies read/write — if your agent will work with companies
  • Deals read/write — if your agent will work with deals
  • Tickets read/write — if your agent will work with tickets

If you plan to use list membership or engagement actions, add the corresponding HubSpot scopes for those APIs as well.

If you plan to resolve associations between CRM records, such as finding a contact's associated company, add read scopes for both object types involved.

If you plan to use meeting scheduling actions, add the HubSpot Meetings Scheduler scopes required for listing meeting links, reading availability, and booking meetings.

For meeting booking, BotDojo exposes the booking duration as durationMinutes so flow builders and agents can use normal minute values. BotDojo converts that value to the millisecond duration field required by HubSpot when it calls the scheduler API, then returns the booked duration as minutes.

Use HubSpot Triggers​

HubSpot triggers let a BotDojo flow run when HubSpot sends CRM webhook events.

BotDojo supports these HubSpot webhook trigger types:

  • contact.creation
  • contact.propertyChange
  • company.creation
  • company.propertyChange

To use them:

  1. In HubSpot, open the Private App that will send webhook events.
  2. Set the webhook target URL to:
https://api.botdojo.com/integrations/hubspot/webhooks/crm
  1. Add the HubSpot event subscriptions your flow needs.
  2. In BotDojo, open the HubSpot integration and confirm Portal ID and Webhook Signing Secret are saved.
  3. In Flow Builder, add a HubSpot trigger to your flow.
  4. For property-change triggers, optionally enter comma-separated property names to filter which changes should run the flow.
  5. Publish the flow.

Trigger property inputs accept comma-separated HubSpot internal property names.

For trigger options that ask for properties, use HubSpot internal property names, not labels. For example:

email, phone, mobilephone, firstname, lastname

For company events:

name, domain, country, calling_vendor, signup_flow

For company triggers, use Associated Contacts to control contact enrichment:

  • None: do not fetch company-contact associations.
  • Primary: include only the primary associated contact when HubSpot marks one.
  • All: include all contacts associated with the company.

When associated contacts are enabled, add Contact Properties to control which contact fields BotDojo fetches and includes.

Trigger Enrichment And API Usage​

HubSpot webhook payloads can contain many events in one request. BotDojo batches trigger enrichment per webhook request so one burst can fetch company properties, company-contact associations, and associated contacts in grouped HubSpot API calls instead of one set of calls per event.

Batch reads are chunked in groups of up to 100 CRM records. Selecting many properties or associated objects can still increase HubSpot API usage, so configure only the fields the flow needs.

If HubSpot rate-limits or rejects an enrichment call, BotDojo still runs matching triggers when possible. The trigger data includes an enrichment object with status and warnings so downstream flows can detect partial enrichment.

HubSpot Trigger Troubleshooting​

  • HubSpot shows 403 responses: verify the BotDojo integration has the correct Portal ID and Webhook Signing Secret for the same Private App that owns the webhook subscriptions.
  • The webhook is authorized but no flow runs: verify the flow is published and the HubSpot trigger is configured for the same event type HubSpot is sending.
  • Property-change events do not run the flow: verify the trigger's property filter uses comma-separated HubSpot internal property names, or leave the filter blank to accept all property changes.
  • Trigger data is missing expected fields: add the relevant contact or company property names to the trigger options so BotDojo fetches and includes them in the trigger data.

Use HubSpot In A Flow​

  1. Open a flow in the Flow Builder.
  2. Add a tool from Integration Tools.
  3. Select the HubSpot action you want, such as Search Contacts, Create Deal, or Get Ticket.
  4. Configure fixed inputs if needed, or let the agent populate inputs dynamically.
  5. Run the flow and verify the HubSpot action succeeds.

Troubleshooting​

Connect fails immediately​

Most likely causes:

  • the token is invalid or expired
  • the Private App is missing Contacts read scope
  • the user who created the Private App no longer has the required HubSpot permissions

The connection succeeds, but specific actions fail later​

That usually means the token is missing the specific scopes needed for the action you chose.

References​