hubspot_get_recent_engagements

Instructions

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
    }
  }