hubspot_get_recent_engagements
Retrieve recent engagement activities from HubSpot CRM contacts and companies to monitor interactions and track communication history.
Instructions
Get recent engagement activities across all contacts and companies
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to look back (default: 7) | |
| limit | No | Maximum number of engagements to return (default: 50) |
Implementation Reference
- src/hubspot-client.ts:202-314 (handler)Core handler function in HubSpotClient that implements the tool logic: fetches recent engagements using HubSpot Engagements API v1, formats data by engagement type (NOTE, EMAIL, TASK, MEETING, CALL), converts datetime fields, and handles errors.async getRecentEngagements(days: number = 7, limit: number = 50): Promise<any> { try { // Calculate the date range (past N days) const endTime = new Date(); const startTime = new Date(endTime); startTime.setDate(startTime.getDate() - days); // Format timestamps for API call const startTimestamp = Math.floor(startTime.getTime()); const endTimestamp = Math.floor(endTime.getTime()); // Get all recent engagements const engagementsResponse = await this.client.apiRequest({ method: 'GET', path: '/engagements/v1/engagements/recent/modified', qs: { count: limit, since: startTimestamp, offset: 0 } }); // Format the engagements similar to company_activity const formattedEngagements = []; // Ensure we have a proper response body const responseBody = engagementsResponse.body as any; for (const engagement of responseBody.results || []) { const engagementData = engagement.engagement || {}; const metadata = engagement.metadata || {}; const formattedEngagement: Record<string, any> = { id: engagementData.id, type: engagementData.type, created_at: engagementData.createdAt, last_updated: engagementData.lastUpdated, created_by: engagementData.createdBy, modified_by: engagementData.modifiedBy, timestamp: engagementData.timestamp, associations: engagement.associations || {} }; // Add type-specific metadata formatting identical to company_activity if (engagementData.type === 'NOTE') { formattedEngagement.content = metadata.body || ''; } else if (engagementData.type === 'EMAIL') { formattedEngagement.content = { subject: metadata.subject || '', from: { raw: metadata.from?.raw || '', email: metadata.from?.email || '', firstName: metadata.from?.firstName || '', lastName: metadata.from?.lastName || '' }, to: (metadata.to || []).map((recipient: any) => ({ raw: recipient.raw || '', email: recipient.email || '', firstName: recipient.firstName || '', lastName: recipient.lastName || '' })), cc: (metadata.cc || []).map((recipient: any) => ({ raw: recipient.raw || '', email: recipient.email || '', firstName: recipient.firstName || '', lastName: recipient.lastName || '' })), bcc: (metadata.bcc || []).map((recipient: any) => ({ raw: recipient.raw || '', email: recipient.email || '', firstName: recipient.firstName || '', lastName: recipient.lastName || '' })), sender: { email: metadata.sender?.email || '' }, body: metadata.text || metadata.html || '' }; } else if (engagementData.type === 'TASK') { formattedEngagement.content = { subject: metadata.subject || '', body: metadata.body || '', status: metadata.status || '', for_object_type: metadata.forObjectType || '' }; } else if (engagementData.type === 'MEETING') { formattedEngagement.content = { title: metadata.title || '', body: metadata.body || '', start_time: metadata.startTime, end_time: metadata.endTime, internal_notes: metadata.internalMeetingNotes || '' }; } else if (engagementData.type === 'CALL') { formattedEngagement.content = { body: metadata.body || '', from_number: metadata.fromNumber || '', to_number: metadata.toNumber || '', duration_ms: metadata.durationMilliseconds, status: metadata.status || '', disposition: metadata.disposition || '' }; } formattedEngagements.push(formattedEngagement); } // Convert any datetime fields and return return convertDatetimeFields(formattedEngagements); } catch (error: any) { console.error('Error getting recent engagements:', error); return { error: error.message }; } }
- src/index.ts:139-157 (registration)Tool registration in the MCP server, including name, description, and input schema definition.{ name: 'hubspot_get_recent_engagements', description: 'Get recent engagement activities across all contacts and companies', inputSchema: { type: 'object', properties: { days: { type: 'number', description: 'Number of days to look back (default: 7)', default: 7 }, limit: { type: 'number', description: 'Maximum number of engagements to return (default: 50)', default: 50 } } } },
- src/index.ts:272-283 (handler)MCP server request handler switch case that invokes the HubSpotClient method and returns JSON response.case 'hubspot_get_recent_engagements': { const result = await this.hubspot.getRecentEngagements( args.days as number | undefined, args.limit as number | undefined ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; }
- src/hubspot-client.ts:7-29 (helper)Helper utility function used by getRecentEngagements to recursively convert Date objects to ISO strings in response data.export function convertDatetimeFields(obj: any): any { if (obj === null || obj === undefined) { return obj; } if (typeof obj === 'object') { if (obj instanceof Date) { return obj.toISOString(); } if (Array.isArray(obj)) { return obj.map(item => convertDatetimeFields(item)); } const result: Record<string, any> = {}; for (const [key, value] of Object.entries(obj)) { result[key] = convertDatetimeFields(value); } return result; } return obj; }