Developer Handover Pack

Developer Handover Pack

Lost Lead Re-engagement

Runs on a scheduled daily trigger at 7:00 AM. Queries the HubSpot Contacts API for all records where the last_activity_date property is more than 21 days in the past and where the lifecycle stage is not 'closedwon' or 'closedlost'. Each matching contact is passed downstream as an individual workflow run, carrying its full contact context payload. A corresponding row is written to the Google Sheets audit log on every trigger so that every initiated outreach is traceable from day one. Duplicate suppression is handled by checking a custom HubSpot property ('re_engagement_active') before queuing; if the property is set to true, the contact is skipped for that run.

// Input
HubSpot scheduled scan
  filter: last_activity_date < (today - 21 days)
  filter: lifecyclestage NOT IN ['closedwon', 'closedlost']
  filter: re_engagement_active != true

// Output (per contact, passed to Sequence Copywriter Agent)
{
  contact_id: string,          // HubSpot internal contact ID
  first_name: string,
  last_name: string,
  email: string,
  assigned_rep_email: string,  // hubspot_owner email
  last_activity_date: ISO8601,
  lifecycle_stage: string,
  deal_stage: string,
  last_note_body: string,      // most recent engagement note text
  company_name: string,
  touch_number: integer        // defaults to 1 on first run
}

// Google Sheets audit log row appended
[contact_id, email, run_timestamp, touch_number, status='queued']

Activated once per contact per sequence touch by the Lead Inactivity Monitor output (touch 1) and by a scheduled re-trigger if no reply is detected after the follow-up interval (touches 2 and 3, spaced five and ten days from the previous send respectively). Uses the full contact context payload to construct a structured prompt for OpenAI. The prompt instructs the model to write a short re-engagement email (120 to 180 words) referencing the specific last interaction, varying the angle across touches: touch 1 uses a value-lead angle, touch 2 uses a social proof or case study hook, and touch 3 uses a low-friction closing question. The drafted email is sent via Gmail from the assigned rep's OAuth-connected account, then logged as an engagement activity on the HubSpot contact record. The next follow-up date is set by writing to the 're_engagement_next_touch_date' custom property.

// Input (from Lead Inactivity Monitor)
{
  contact_id: string,
  first_name: string,
  last_name: string,
  email: string,
  assigned_rep_email: string,
  last_note_body: string,
  company_name: string,
  touch_number: integer,       // 1, 2, or 3
  deal_stage: string
}

// OpenAI prompt construction (illustrative)
system: 'You are a sales assistant writing re-engagement emails on behalf of a rep.
         Keep the tone warm, direct, and concise (120-180 words).
         Touch 1: lead with value. Touch 2: social proof hook. Touch 3: low-friction close.'
user:   'Contact: {first_name} {last_name} at {company_name}.
         Last interaction note: {last_note_body}.
         Deal stage at last contact: {deal_stage}.
         This is touch number {touch_number}. Write the email now.'

// Output
{
  subject_line: string,
  email_body: string,
  sent_at: ISO8601,
  gmail_message_id: string,    // stored for reply thread matching
  hubspot_activity_id: string  // returned after logging
}

// HubSpot properties written after send
re_engagement_active: true
re_engagement_touch_number: {touch_number}
re_engagement_last_sent_at: {sent_at}
re_engagement_next_touch_date: {sent_at + interval_days}
re_engagement_gmail_thread_id: {gmail_thread_id}

Monitors the Gmail inbox of each connected rep account for replies that match a tracked re-engagement thread ID. When a reply is detected, the full reply body is passed to OpenAI for intent classification. The model classifies the reply into one of four categories: interested (warm), neutral (non-committal), unsubscribe (opt-out), or out-of-office (auto-reply). Warm replies trigger an immediate Slack message to the assigned rep via a channel webhook, including the lead name, a one-sentence reply summary, and a direct HubSpot contact URL. Unsubscribe replies suppress the sequence by clearing 're_engagement_active' and setting a 'do_not_contact' flag in HubSpot. Out-of-office replies pause the sequence by adjusting the next touch date. When no reply is received after the third touch, the workflow updates the contact lifecycle stage to Closed Lost and clears all re-engagement properties.

// Input: reply detected
{
  gmail_thread_id: string,     // matched against stored re_engagement_gmail_thread_id
  reply_body: string,
  reply_from_email: string,
  received_at: ISO8601,
  contact_id: string,          // looked up via thread_id match
  assigned_rep_email: string
}

// OpenAI classification prompt
system: 'Classify this email reply into exactly one of: interested, neutral, unsubscribe, out-of-office.'
user:   '{reply_body}'

// Output: intent = 'interested'
Slack webhook POST to rep channel:
{
  text: 'Warm reply from {first_name} {last_name} ({company_name}).
         Summary: {one_sentence_summary}.
         HubSpot: https://app.hubspot.com/contacts/{portal_id}/contact/{contact_id}'
}
HubSpot property writes:
  re_engagement_reply_intent: 'interested'
  re_engagement_active: false

// Output: intent = 'unsubscribe'
HubSpot property writes:
  re_engagement_active: false
  hs_email_optout: true
  re_engagement_reply_intent: 'unsubscribe'

// Output: intent = 'out-of-office'
HubSpot property writes:
  re_engagement_next_touch_date: {received_at + 7 days}

// Output: no reply after touch 3 (sequence complete)
HubSpot property writes:
  lifecyclestage: 'closedlost'
  re_engagement_active: false
  re_engagement_touch_number: 3
  re_engagement_final_outcome: 'no_reply'

// ============================================================
// LOST LEAD RE-ENGAGEMENT: END-TO-END DATA FLOW
// ============================================================

// TRIGGER
// Scheduled cron fires at 07:00 AM daily
// ============================================================
CRON_TRIGGER -> HubSpot Contacts API
  GET /crm/v3/objects/contacts
  filter: last_activity_date < (today - P21D)
  filter: lifecyclestage NOT IN ['closedwon', 'closedlost']
  filter: re_engagement_active != true
  returns: [ contact_id, first_name, last_name, email,
             hubspot_owner_id, lifecyclestage, last_activity_date ]

// --- AGENT HANDOFF 1: Lead Inactivity Monitor -> Sequence Copywriter Agent ---

// For each contact in result set:
HubSpot Contacts API -> fetch full record
  GET /crm/v3/objects/contacts/{contact_id}
  properties: [ first_name, last_name, email, company,
                deal_stage, hs_latest_meeting_notes,
                notes_last_updated, re_engagement_touch_number ]
  resolve owner: GET /crm/v3/owners/{hubspot_owner_id}
    returns: assigned_rep_email

HubSpot -> Google Sheets audit log
  APPEND row:
  [ contact_id, email, run_timestamp, touch_number=1, status='queued' ]

// Payload passed to Sequence Copywriter Agent
contact_payload = {
  contact_id, first_name, last_name, email, company_name,
  assigned_rep_email, last_note_body, deal_stage, touch_number
}

// ============================================================
// SEQUENCE COPYWRITER AGENT
// ============================================================

contact_payload -> OpenAI Chat Completions API
  POST /v1/chat/completions
  model: gpt-4o
  max_tokens: 400
  temperature: 0.7
  messages: [ system_prompt, user_prompt(contact_payload) ]
  returns: { subject_line, email_body }

{ subject_line, email_body } -> Gmail API
  POST /gmail/v1/users/{assigned_rep_email}/messages/send
  to: contact.email
  from: assigned_rep_email
  subject: subject_line
  body: email_body
  returns: { gmail_message_id, gmail_thread_id }

{ gmail_message_id, gmail_thread_id, sent_at } -> HubSpot
  POST /crm/v3/objects/engagements   // log email activity
    type: EMAIL
    associations: [ contact_id ]
    metadata: { subject: subject_line, body: email_body, sentAt: sent_at }
  PATCH /crm/v3/objects/contacts/{contact_id}
    re_engagement_active: true
    re_engagement_touch_number: touch_number
    re_engagement_last_sent_at: sent_at
    re_engagement_next_touch_date: sent_at + interval_days
    re_engagement_gmail_thread_id: gmail_thread_id

Google Sheets audit log
  UPDATE row: status='sent', email_subject=subject_line, sent_at=sent_at

// Re-trigger logic (touches 2 and 3):
// Orchestration layer polls HubSpot daily for contacts where:
//   re_engagement_active = true
//   re_engagement_next_touch_date <= today
//   re_engagement_reply_intent IS NULL
// If condition met, increment touch_number and re-enter Sequence Copywriter Agent

// --- AGENT HANDOFF 2: Sequence Copywriter Agent -> Reply Classifier and Router ---

// ============================================================
// REPLY CLASSIFIER AND ROUTER
// ============================================================

// Gmail inbox poll (every 15 minutes per rep account)
Gmail API
  GET /gmail/v1/users/{assigned_rep_email}/messages
  q: 'in:inbox newer_than:15m'
  for each message: GET /gmail/v1/users/{me}/messages/{message_id}
    extract: thread_id, from_email, reply_body, received_at
  match thread_id against HubSpot re_engagement_gmail_thread_id
  if no match: skip and log to audit sheet

reply_body -> OpenAI Chat Completions API
  POST /v1/chat/completions
  model: gpt-4o
  messages: [ classification_system_prompt, user_prompt(reply_body) ]
  returns: intent_classification // 'interested'|'neutral'|'unsubscribe'|'out-of-office'

// ROUTE: intent = 'interested'
intent='interested' -> Slack Incoming Webhook
  POST {slack_webhook_url}
  payload: { text: 'Warm reply: {first_name} {last_name} ({company_name}).
              Summary: {reply_summary}. Link: {hubspot_contact_url}' }
-> HubSpot PATCH /crm/v3/objects/contacts/{contact_id}
    re_engagement_reply_intent: 'interested'
    re_engagement_active: false

// ROUTE: intent = 'unsubscribe'
intent='unsubscribe' -> HubSpot PATCH
    re_engagement_active: false
    hs_email_optout: true
    re_engagement_reply_intent: 'unsubscribe'

// ROUTE: intent = 'out-of-office'
intent='out-of-office' -> HubSpot PATCH
    re_engagement_next_touch_date: received_at + P7D

// ROUTE: intent = 'neutral'
intent='neutral' -> no action, sequence continues on next touch date

// ROUTE: sequence complete, no reply (touch_number = 3, no reply after interval)
-> HubSpot PATCH /crm/v3/objects/contacts/{contact_id}
    lifecyclestage: 'closedlost'
    re_engagement_active: false
    re_engagement_final_outcome: 'no_reply'
-> Google Sheets audit log UPDATE: final_outcome='closed_lost'

// ============================================================
// END OF FLOW
// ============================================================