Engagement Response

Engagement Response is the workflow behind Sam, HeyCMO's Community Manager agent. It pulls comments, mentions, and DMs from every connected social channel, classifies each one (lead, question, complaint, positive, spam), drafts an on-brand reply, and routes it through an approval queue before posting. By default every reply is reviewed by the customer until trust is established — auto-send is opt-in.

Configuration

How a run flows

1. Drain x-stream brand mentions — drainXStreamBrandMentions(customerId) reads up to 50 unconsumed x_stream_brand_mention events from the last 24 hours (older events are skipped — stale brand mentions get archived, not auto-replied days later). Each event becomes a comment in the same shape as Composio-fetched comments.

2. Fetch Composio comments — Per connected channel, the workflow asks Composio for the latest unread comments and DMs.

3. Sanitize for prompt — formatCommentsForPrompt strips control chars and normalizes whitespace; the agent never sees raw user input.

4. Classify each comment with the engagement agent. Output:

   {
     classification: 'lead' | 'question' | 'complaint' | 'positive' | 'spam',
     response: string | undefined,
     action: 'replied' | 'dm_sent' | 'escalated' | 'thanked' | 'ignored',
   }

5. Route by classification:

   Classification	Default action
   lead	Draft a reply + queue a lead-gen handoff to Mia
   question	Draft a helpful reply, escalate to support if account-specific
   complaint	Always escalate to a human first; draft a draft-only reply
   positive	Brief thank-you, lower priority
   spam	Ignore (no reply written, event archived)

6. Approval queue — Every drafted reply is parked in the customer's approval inbox. The customer approves, edits, or rejects. Approved replies are sent via Composio (or X v2 API for X). Rejected replies are archived with the reason.

7. Mark x-stream events consumed — Once handled, the workflow writes a x_stream_consumed sibling event so the next drain run skips it. See X Stream Router for the append-only consumed pattern.

Auto-reply opt-in

Auto-reply is opt-in per channel and per classification — e.g. a customer might trust Sam to auto-thank positive mentions on LinkedIn but require approval for everything on X. The flag lives on BrandConfig.engagementAutoReplyChannels and is consulted on every reply attempt.

The default-off posture is deliberate: a single bad auto-reply on a public timeline is a brand-safety incident the customer can't undo. Trust is earned by reviewing the first ~50 drafts; once the customer has approved a stretch of replies untouched, the dashboard surfaces an "enable auto-reply" prompt for that channel.

Memory + context

The workflow uses the shared Mastra memory store scoped to the tenant id (resolveTenantId). That means Sam remembers:

• Past conversations with the same author (so a follow-up reply doesn't re-introduce HeyCMO)
• The brand kernel (voice, do-not-say list, signature phrases)
• Recent customer complaints, so an escalation doesn't get drafted twice

Output summary

Every run returns a structured summary that lands in the customer's morning briefing:

{
  "handled": 42,
  "leads": 6,
  "escalated": 2,
  "replies": 28,
  "summary": "28 replies drafted (4 already auto-sent on LinkedIn). 6 leads handed to Mia. 2 complaints escalated — both about the new pricing page."
}

Where to look in the code

• apps/api/agent/workflows/engagement-response.ts — workflow definition
• apps/api/agent/agents/engagement.ts — Sam's instructions and tools
• apps/api/agent/lib/comment-sanitize.ts — prompt-safe formatting
• apps/api/agent/lib/x-stream-router.ts — upstream classifier
• apps/api/agent/workflows/__tests__/lead-outreach.test.ts — integration via the lead handoff path

Related

• X Stream Router — where brand-mention events come from
• LinkedIn Outreach — the partner workflow for cold LinkedIn DMs
• Cold Email — same approval-queue pattern applied to outbound email