HubSpot Integration
Relevant source files
The following files were used as context for generating this wiki page:The HubSpot integration for Quix provides an AI-powered interface to interact with the HubSpot CRM platform directly from Slack. Users can manage contacts, companies, deals, tasks, and tickets using natural language queries. The integration leverages the Quix agent architecture to understand user intent, select the appropriate HubSpot tool, and execute actions via the HubSpot API.
This system is designed to be a modular package within the Quix monorepo, located at agent-packages/packages/hubspot/. It exposes a set of tools that the core LLM service can utilize to fulfill user requests related to HubSpot data.
Sources: README.md, src/lib/constants.ts:80-88, agent-packages/packages/hubspot/src/tools.ts
Architecture and Configuration
The HubSpot integration is encapsulated as a tool package that is initialized and passed to the Quix agent. The primary entry point for creating the toolset is the createHubspotToolsExport function.
Sources: agent-packages/packages/hubspot/src/tools.ts:68-70
Configuration
To enable the integration, a HubspotConfig object must be provided. This configuration is stored and managed within the main application's database and is associated with a specific Slack workspace.
// From agent-packages/packages/hubspot/src/types.ts
export interface HubspotConfig extends BaseConfig {
accessToken: string;
hubId: number;
}
Sources: agent-packages/packages/hubspot/src/types.ts:11-14
The configuration is used to instantiate the HubspotService, which handles all communication with the HubSpot API.
Sources: agent-packages/packages/hubspot/src/tools.ts:69
OAuth Scopes
The integration requires specific OAuth scopes to function correctly. These are defined centrally and used during the OAuth installation flow.
| Scope | Description |
|---|---|
crm.objects.contacts.read | Read contacts |
crm.objects.contacts.write | Create and update contacts |
crm.objects.companies.read | Read companies |
crm.objects.companies.write | Create and update companies |
crm.objects.deals.read | Read deals |
crm.objects.deals.write | Create and update deals |
crm.objects.owners.read | Read owner (user) information |
tickets | Read, create, and update support tickets |
Sources: src/lib/constants.ts:18-27
Tool Export Flow
The following diagram illustrates how the HubSpot tools are created and configured.
This diagram shows the createHubspotToolsExport function taking a configuration and producing a ToolConfig object containing the executable tools and LLM prompts.
Sources: agent-packages/packages/hubspot/src/tools.ts:68-239
Core Entities
The integration is built to interact with several key HubSpot CRM objects. The primary entities are:
- Contacts: Individuals in the CRM.
- Companies: Organizations associated with contacts and deals.
- Deals: Sales opportunities with stages, amounts, and close dates.
- Tasks: To-do items that can be associated with other entities.
- Tickets: Support cases for tracking customer issues.
This ER diagram shows the relationships between the main HubSpot entities managed by the integration.
Sources: agent-packages/packages/hubspot/src/types.ts, agent-packages/packages/hubspot/src/tools.ts:168-173, agent-packages/packages/hubspot/src/tools.ts:200-205, agent-packages/packages/hubspot/src/tools.ts:226-231
Available Tools
A suite of tools is provided to perform CRUD (Create, Read, Update, Delete) operations on HubSpot entities. Each tool is defined with a Zod schema for input validation.
Sources: agent-packages/packages/hubspot/src/tools.ts:72-237
General Tools
| Tool Name | Description | Operations |
|---|---|---|
get_hubspot_pipelines | Retrieve all pipelines for a specific object type (tickets or deals). | READ |
get_hubspot_properties | Get all properties for an object type (ticket, deal, or contact), including custom fields. | READ |
get_hubspot_owners | Fetch all HubSpot owners (users) and their IDs. | READ |
Deal Tools
| Tool Name | Description | Operations |
|---|---|---|
search_hubspot_deals | Search for deals in HubSpot. | READ |
create_hubspot_deal | Create a new deal in HubSpot. | CREATE |
update_hubspot_deal | Update an existing HubSpot deal. | UPDATE |
add_note_to_hubspot_deal | Add a note to a deal in HubSpot. | CREATE |
associate_deal_with_entity | Associate an existing deal with a HubSpot contact, company, or deal. | UPDATE |
Contact & Company Tools
| Tool Name | Description | Operations |
|---|---|---|
search_hubspot_contacts | Search for contacts based on name or email. | READ |
create_hubspot_contact | Create a new contact in HubSpot. | CREATE |
update_hubspot_contact | Update an existing HubSpot contact. | UPDATE |
add_note_to_hubspot_contact | Add a note to a contact in HubSpot. | CREATE |
search_hubspot_companies | Search companies based on a keyword. | READ |
add_note_to_hubspot_company | Add a note to a company in HubSpot. | CREATE |
Task Tools
| Tool Name | Description | Operations |
|---|---|---|
search_hubspot_tasks | Search for tasks using filters like keyword, owner, status, etc. | READ |
create_hubspot_task | Create a new HubSpot task. | CREATE |
update_hubspot_task | Update the details of an existing task. | UPDATE |
associate_task_with_entity | Associate an existing task with a contact, company, or deal. | UPDATE |
Ticket Tools
| Tool Name | Description | Operations |
|---|---|---|
search_hubspot_tickets | Search for tickets based on keyword, owner, stage, or priority. | READ |
create_hubspot_ticket | Create a new HubSpot ticket. | CREATE |
update_hubspot_ticket | Update an existing HubSpot ticket. | UPDATE |
associate_ticket_with_entity | Associate an existing ticket with a contact, company, or deal. | UPDATE |
Data Schemas
Input validation for each tool is handled by Zod schemas. These schemas define the expected parameters, types, and descriptions for the arguments passed to each tool function.
Sources: agent-packages/packages/hubspot/src/schema.ts
Example: createDealSchema
This schema defines the required and optional fields for creating a new deal.
| Parameter | Type | Description |
|---|---|---|
dealname | string | The name of the deal. |
companyId | string | The associated company ID. |
contactId | string | The associated contact ID. |
amount | number | The deal amount. |
dealstage | string | The deal stage. |
closedate | string | The close date (YYYY-MM-DD). |
pipeline | string | The pipeline ID. |
ownerId | string | The owner ID. |
Sources: agent-packages/packages/hubspot/src/schema.ts:182-187
Example: taskSearchSchema
This schema is used for searching tasks with various filters.
| Parameter | Type | Description |
|---|---|---|
keyword | string | Keyword to search in task titles or descriptions. |
ownerId | string | Filter tasks by the owner's ID. |
status | enum | Filter by task status (NOT_STARTED, COMPLETED, etc.). |
priority | enum | Filter by task priority (HIGH, MEDIUM, LOW). |
dueDateFrom | string | Start date for due date range (YYYY-MM-DD). |
dueDateTo | string | End date for due date range (YYYY-MM-DD). |
Sources: agent-packages/packages/hubspot/src/schema.ts:46-65
LLM Interaction
The integration provides specific prompts to guide the LLM in selecting and using the HubSpot tools effectively.
HUBSPOT_TOOL_SELECTION_PROMPT: This prompt helps the LLM decide when to use HubSpot tools. It describes the types of data managed by HubSpot (Contacts, Companies, Deals, Tasks, Tickets) and gives examples of user queries that would warrant using these tools.HUBSPOT_RESPONSE_GENERATION_PROMPT: This prompt instructs the LLM on how to format the data returned from HubSpot tools into a user-friendly response. It suggests formatting conventions like using bold for important details and presenting deal values clearly.
Sources: agent-packages/packages/hubspot/src/tools.ts:26-66
Example Usage Flow
The following sequence diagram shows how a user request to create a HubSpot ticket is processed.
This diagram is based on a test case that demonstrates a multi-step process involving several tool calls to fulfill a single user request.
Sources: src/llm/agent-evals/hubspot-agent/test-data.ts:192-263
Summary
The HubSpot integration is a powerful component of the Quix platform, enabling seamless interaction with a wide range of HubSpot CRM functionalities directly from Slack. Its modular design, comprehensive toolset, and clear separation of concerns (service, tools, schemas) make it a robust and extensible part of the agent ecosystem. By providing detailed prompts and structured tools, it allows the LLM to intelligently manage CRM data on behalf of the user, streamlining workflows and improving productivity.
Sources: README.md, agent-packages/packages/hubspot/src/tools.ts