hubspot-get-link
Generate HubSpot UI links for specific object details or index pages using object types and IDs. Validate object type IDs and create accurate references to HubSpot records.
Instructions
🎯 Purpose:
1. Generates HubSpot UI links for different pages based on object types and IDs.
2. Supports both index pages (lists of objects) and record pages (specific object details).
📋 Prerequisites:
1. Use the hubspot-get-user-details tool to get the PortalId and UiDomain.
🧭 Usage Guidance:
1. Use to generate links to HubSpot UI pages when users need to reference specific HubSpot records.
2. Validates that object type IDs exist in the HubSpot system.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageRequests | Yes | Array of page link requests to generate | |
| portalId | Yes | The HubSpot portal/account ID | |
| uiDomain | Yes | The HubSpot UI domain(e.g., 'app.hubspot.com') |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"pageRequests": {
"description": "Array of page link requests to generate",
"items": {
"additionalProperties": false,
"properties": {
"objectId": {
"description": "The specific object ID to link to (required for 'record' page types)",
"type": "string"
},
"objectTypeId": {
"description": "The HubSpot object type ID to link to (e.g., '0-1', '0-2' for contacts, companies, or '2-x' for custom objects)",
"type": "string"
},
"pagetype": {
"description": "The type of page to link to: 'record' for a specific object's page, 'index' for a list page",
"enum": [
"record",
"index"
],
"type": "string"
}
},
"required": [
"pagetype",
"objectTypeId"
],
"type": "object"
},
"type": "array"
},
"portalId": {
"description": "The HubSpot portal/account ID",
"type": "string"
},
"uiDomain": {
"description": "The HubSpot UI domain(e.g., 'app.hubspot.com')",
"type": "string"
}
},
"required": [
"portalId",
"uiDomain",
"pageRequests"
],
"type": "object"
}
Implementation Reference
- dist/tools/toolsRegistry.js:45-45 (registration)Registers the instance of GetHubspotLinkTool with the tool registry.registerTool(new GetHubspotLinkTool());
- ToolDefinition object providing the tool name, description, input schema (derived from Zod schema), and annotations.const ToolDefinition = { name: 'hubspot-get-link', description: ` 🎯 Purpose: 1. Generates HubSpot UI links for different pages based on object types and IDs. 2. Supports both index pages (lists of objects) and record pages (specific object details). 📋 Prerequisites: 1. Use the hubspot-get-user-details tool to get the PortalId and UiDomain. 🧭 Usage Guidance: 1. Use to generate links to HubSpot UI pages when users need to reference specific HubSpot records. 2. Validates that object type IDs exist in the HubSpot system. `, inputSchema: zodToJsonSchema(GetHubspotLinkSchema), annotations: { title: 'Get HubSpot Link', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, };
- Zod schemas defining the input structure: PageTypeEnum, PageRequestSchema, and GetHubspotLinkSchema used to generate JSON schema for the tool.const PageTypeEnum = z .enum(['record', 'index']) .describe("The type of page to link to: 'record' for a specific object's page, 'index' for a list page"); const PageRequestSchema = z.object({ pagetype: PageTypeEnum, objectTypeId: z .string() .describe("The HubSpot object type ID to link to (e.g., '0-1', '0-2' for contacts, companies, or '2-x' for custom objects)"), objectId: z .string() .optional() .describe("The specific object ID to link to (required for 'record' page types)"), }); const GetHubspotLinkSchema = z.object({ portalId: z.string().describe('The HubSpot portal/account ID'), uiDomain: z.string().describe("The HubSpot UI domain(e.g., 'app.hubspot.com')"), pageRequests: z.array(PageRequestSchema).describe('Array of page link requests to generate'), });
- The GetHubspotLinkTool class implements the core logic: validation of inputs using helper methods and generation of HubSpot UI links for object index or record pages.export class GetHubspotLinkTool extends BaseTool { constructor() { super(GetHubspotLinkSchema, ToolDefinition); } async process(args) { const { portalId, uiDomain, pageRequests } = args; const validationResult = this.validateRequests(pageRequests); if (validationResult.errors.length > 0) { return this.formatErrorResponse(validationResult); } const urlResults = this.generateUrls(portalId, uiDomain, pageRequests); return { content: [ { type: 'text', text: JSON.stringify(urlResults, null, 2), }, ], }; } isValidObjectTypeId(objectTypeId) { if (Object.keys(HUBSPOT_ID_TO_OBJECT_TYPE).includes(objectTypeId)) { return true; } if (objectTypeId.startsWith('2-')) { return true; } return false; } validateRequests(pageRequests) { const errors = []; const invalidObjectTypeIds = []; for (const request of pageRequests) { const { pagetype, objectTypeId, objectId } = request; // Validate objectTypeId exists if (!this.isValidObjectTypeId(objectTypeId)) { invalidObjectTypeIds.push(objectTypeId); errors.push(`Invalid objectTypeId: ${objectTypeId}`); continue; } // For record pages, objectId is required if (pagetype === 'record' && !objectId) { errors.push(`objectId is required for record page with objectTypeId: ${objectTypeId}`); } } return { errors, invalidObjectTypeIds }; } formatErrorResponse(validationResult) { const errorResponse = { errors: validationResult.errors, }; // Add valid object type IDs only once if there were invalid IDs if (validationResult.invalidObjectTypeIds.length > 0) { errorResponse.validObjectTypeIds = Object.keys(HUBSPOT_ID_TO_OBJECT_TYPE); errorResponse.validObjectTypeIds.push('2-x (where x is your custom object ID)'); } return { content: [ { type: 'text', text: JSON.stringify(errorResponse, null, 2), }, ], isError: true, }; } generateUrls(portalId, uiDomain, pageRequests) { return pageRequests.map(request => { const { pagetype, objectTypeId, objectId } = request; let url = ''; if (pagetype === 'index') { url = `https://${uiDomain}/contacts/${portalId}/objects/${objectTypeId}`; } else { url = `https://${uiDomain}/contacts/${portalId}/record/${objectTypeId}/${objectId}`; } return { pagetype, objectTypeId, objectId, url, }; }); } }
- dist/types/objectTypes.js:48-51 (helper)Helper constant mapping HubSpot object type IDs to object type names, used in isValidObjectTypeId for validation.export const HUBSPOT_ID_TO_OBJECT_TYPE = Object.entries(HUBSPOT_OBJECT_TYPE_TO_ID).reduce((acc, [objectType, id]) => ({ ...acc, [id]: objectType, }), {});