HubSpot

Overview

HubSpot tools give your agents access to a wide range of HubSpot objects. Agents can make account summaries and create contacts, deals, opportunities, tickets, and more. This document provides general information about our HubSpot tools (available tools, setup and authentication) but as the tool will likely evolve, the fresh list of available tools can be found when you are actually connecting the Hubspot tool in your workspace.

Available Tools

Tool	Description
Get Object Properties	Lists all available properties for a HubSpot object. When creatableOnly is true, returns only properties that can be modified through forms (excludes hidden, calculated, read-only and file upload fields).
Create Contact	Creates a new contact in Hubspot, with optional associations.
Get Object By Email	Retrieves a Hubspot object using an email address. Supports contacts, companies, deals, owners.
Count Objects By Properties	Count objects in Hubspot with matching properties. Supports contacts, companies, deals. Max limit is 10000 objects.
Get Latest Objects	Get latest objects from Hubspot. Supports contacts, companies, deals. Limit is 50.
Create Company	Creates a new company in Hubspot, with optional associations.
Create Deal	Creates a new deal in Hubspot, with optional associations.
Create Lead	Creates a new lead in Hubspot (as a Deal), with optional associations. Ensure properties correctly define it as a lead.
Create Task	Creates a new task in Hubspot, with optional associations.
Create Ticket	Creates a new ticket in Hubspot, with optional associations.
Create Note	Creates a new note in Hubspot, with optional associations.
Create Communication	Creates a new communication (WhatsApp, LinkedIn, SMS) in Hubspot as an engagement. Requires hs_communication_channel_type in properties.
Create Meeting	Creates a new meeting in Hubspot as an engagement. Ensure hs_engagement_type=‘MEETING’ and meeting details are in properties.
Get Contact	Retrieves a Hubspot contact by its ID.
Get Company	Retrieves a Hubspot company by its ID.
Get Deal	Retrieves a Hubspot deal by its ID.
Get Meeting	Retrieves a Hubspot meeting (engagement) by its ID.
Get File Public Url	Retrieves a publicly available URL for a file in HubSpot.
Get Associated Meetings	Retrieves meetings associated with a specific object (contact, company, or deal).
Search Crm Objects	Searches CRM objects, including contacts, companies, deals, leads, tickets, and activity records such as tasks, notes, meetings, calls, and emails.
Export Crm Objects Csv	Exports any object type, including tickets, to a CSV file for table queries, up to 2,000 rows per export.

Tickets

Tickets are a supported object. Your agent can search tickets and their fields (status, pipeline, priority, ticket content) with Search Crm Objects, create tickets with Create Ticket, and export a list of tickets to CSV with Export Crm Objects Csv. There isn’t a dedicated tool to pull a ticket’s full history in one go. Listing associations currently only works for contacts, companies, and deals, so a ticket’s related emails, notes, and calls aren’t reachable that way today. If your agent needs a ticket’s related activity, have it search those activity records directly and match them to the ticket.

Workspace Setup and Authentication

See Managing Tools for details on how to make HubSpot tools available to your workspace. The setup will require authentication to HubSpot by the admin. Through the OAuth flow the admin will select that will be accessible by this integration. When connecting the tool as an admin, you will be able to pick between Personal and Workspace authentication.

Workspace means all agents will use the connecting admin’s account when querying Hubspot
Personal means users will need to authenticate the first time they use an agent that has Hubspot access and the actions will then be taken through their account (permissions, audit, etc)

If HubSpot reports that you do not have permission to install the app while completing OAuth, the HubSpot user authorizing the app must be a Super Admin or have the HubSpot Marketplace Access permission. Ask your HubSpot admin to grant this permission, then retry the connection.

HubSpot permissions

When you connect HubSpot, Dust asks HubSpot for the permissions (OAuth scopes) below. Only oauth is required. The others are optional: if your HubSpot account can’t grant one, the connection still works, but agents can’t reach the matching objects.

HubSpot feature	Scopes
Contacts	`crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.schemas.contacts.read`
Companies	`crm.objects.companies.read`, `crm.objects.companies.write`, `crm.schemas.companies.read`
Deals	`crm.objects.deals.read`, `crm.objects.deals.write`, `crm.schemas.deals.read`
Leads	`crm.objects.leads.read`, `crm.objects.leads.write`
Owners	`crm.objects.owners.read`
Custom objects	`crm.schemas.custom.read`, `crm.objects.custom.read`, `crm.objects.custom.write`
Quotes and line items	`crm.objects.quotes.read`, `crm.objects.line_items.read`
Products	`crm.objects.products.read`
Lists	`crm.lists.read`, `crm.lists.write`
Tickets	`tickets`
Files	`files`
Sales emails	`sales-email-read`
Timeline events	`timeline`
Marketing emails	`marketing-email`
CMS content	`content`

With Personal authentication, each user’s connection can only get the permissions the Workspace connection was granted.

Marketing campaigns and campaign revenue reporting aren’t covered: Dust doesn’t request marketing.campaigns.read or marketing.campaigns.revenue.read. Requests to the HubSpot campaigns object or revenue attribution fail with a 403 MISSING_SCOPES error, and reconnecting HubSpot won’t add these permissions. Reconnecting can only add scopes from the list above.

Adding HubSpot Tools to agents

HubSpot tools can be added to an agent by selecting them in the agent builder. They require no configuration. Note that when connecting a tool, you can define the provided tools as high stake or low stake.

We highly recommend leaving any tool that can modify data in your CRM in HIGH STAKE.

In general you will want to mention in the instructions of your agents the objects you want them to interact with. Example instructions:

From the transcripts you are receiving, create a contact if you can't find any existing contact with the interlocutor's name or email, and if a deal has been set create a deal to attach to the current account.

Latest Updates

Use cases

Agents

Skills

Capabilities

Pods

Admins

Developers

Deprecated

Overview

Available Tools

Tickets

Workspace Setup and Authentication

HubSpot permissions

Adding HubSpot Tools to agents

​Overview

​Available Tools

​Tickets

​Workspace Setup and Authentication

​HubSpot permissions

​Adding HubSpot Tools to agents

Overview

Available Tools

Tickets

Workspace Setup and Authentication

HubSpot permissions

Adding HubSpot Tools to agents