hubspot_get_recent_engagements
Retrieve recent engagement activities from HubSpot CRM for contacts and companies to track interactions and monitor relationship 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 that queries HubSpot's engagements API for recent engagements (notes, emails, tasks, meetings, calls) within the given number of days, formats the response consistently, 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:272-282 (handler)MCP server dispatch handler for the tool; parses arguments, calls the HubspotClient's getRecentEngagements method, and returns the result as JSON text 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/index.ts:139-157 (registration)Tool registration in the listTools response, 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:144-155 (schema)Input schema definition for the tool parameters (days and limit with defaults).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 } }