Skip to content

Yes Bot Product Spec

Purpose

  • The Yes Bot handles positive inbound campaign responses in message-inbound.
  • It is an AI-driven workflow, not a hardcoded keyword responder.
  • The AI decides intent and workflow signals.
  • The application maps those signals into CRM actions.

Scope

  • Applies only to inbound SMS handled by supabase/functions/message-inbound/index.ts.
  • Applies only to the AI yes-intent path: message-inbound -> ai-runner /yes-intent -> ai-agent -> ai-yes-intent-update-from-agent
  • Does not own vehicle creation or vehicle extraction. That belongs to the vehicle extraction/apply pipeline.

Runtime Controls

  • The Yes Bot can be turned on or off in AI Administration.
  • The toggle is stored in global_settings:
  • global_type = 'AI'
  • global_key = 'yes_agent_enabled'
  • The Yes Bot is also time-gated.
  • Active hours are stored in global_settings:
  • global_key = 'agent_start_time'
  • global_key = 'agent_end_time'
  • Default active hours:
  • 07:00
  • 20:00
  • Time evaluation uses America/Phoenix.
  • Outside the configured active hours, the Yes Bot does not run.

Entry Conditions

  • The message must be inbound.
  • yes_agent_enabled must be true.
  • Current Phoenix time must be within the configured active window.
  • The no-intent bot must not already detect the message as a no-intent case.
  • The thread must pass the existing yes gate:
  • campaign-response path, or
  • first inbound after an AI-closed thread reevaluation path
  • The lead must have an active lead_opportunity.lead_opportunity_stage in:
  • Initial
  • Potential
  • Closing

AI Contract

  • The Yes Bot prompt lives in cloudflare/ai-agent/src/shared/prompts/prompt-convo-yes.txt.
  • The model returns structured JSON with:
  • detected
  • confidence
  • response
  • should_send_response
  • billing_intent
  • language_intent

Architecture Rule

  • AI owns interpretation.
  • Application code owns execution.
  • The application should not invent business meaning with fallback heuristics.
  • If the AI response is missing, invalid, or unusable, the system should fail closed.

Detection Behavior

  • The Yes Bot is not limited to literal yes.
  • It is intended to detect customer buying interest or willingness to continue service discussion.
  • Examples include:
  • proceed intent
  • repair/replacement interest
  • damage disclosure
  • pricing/process questions tied to service
  • Spanish buying-intent messages

Response Behavior

  • SMS is sent only when all of the following are true:
  • detected = true
  • should_send_response = true
  • response is non-empty
  • If any of those are not true, no Yes Bot SMS is sent.
  • There is no local fallback Yes Bot SMS.
  • The system should not send an English fallback when AI intended a Spanish response.

Vehicle-Aware Reply Rule

  • If the customer names a vehicle in the latest message, the AI should prefer a vehicle-specific insurance question instead of asking for the vehicle again.
  • Example:
  • customer: I want to fix my Ford windshield
  • preferred reply: Great, what insurance do you have on the Ford?
  • This should be handled by the prompt/model response, not local fallback logic.

Stage Mapping

  • The application maps AI signals into enum-backed CRM stage values.
  • AI does not choose enum names directly.

Lead Opportunity Stage

  • On Yes Bot advancement, lead_opportunity_stage is moved to Potential.

Lead Stage Status Mapping

  • Default:
  • PC lead -> PC - Potential
  • non-PC lead -> Potential
  • Cash / no insurance:
  • PC lead -> PC - Cash
  • non-PC lead -> Potential - Cash
  • Spanish:
  • PC lead -> PC - Spanish
  • non-PC lead -> Potential - Spanish
  • Spanish + cash:
  • PC lead -> PC - Cash
  • non-PC lead -> Cash - Spanish

Spanish Rule

  • language_intent = "spanish" should influence stage routing.
  • Spanish stage movement may still occur even when no SMS is sent.
  • If the yes gate is open and the AI returns Spanish language intent, the system may move the lead into the Spanish stage path even when detected = false.

Thread State

  • When the Yes Bot advances the workflow, the thread should be marked:
  • thread.is_closed_by_ai = 2
  • This is handled in supabase/functions/ai-yes-intent-update-from-agent/index.ts.

Vehicle Opportunity Alignment

  • When the Yes Bot advances a lead from initial-response style status to potential style status, eligible vehicle opportunities should be moved to the aligned lead-stage status as well.
  • This keeps vehicle opportunity records consistent with the promoted lead state.

Fail-Closed Rules

  • If AI fails, the Yes Bot should not send a fallback response.
  • If AI response parsing fails, the Yes Bot should not send a fallback response.
  • If AI returns no usable response, the Yes Bot should not send a fallback response.
  • The code should not reintroduce local heuristic yes-response generation.

Admin Requirements

  • AI Administration must expose:
  • Yes Agent on/off
  • No Agent on/off
  • Start time
  • End time
  • These values are saved in global_settings.
  • Runtime entry: supabase/functions/message-inbound/index.ts
  • Yes workflow updater: supabase/functions/ai-yes-intent-update-from-agent/index.ts
  • AI prompt: cloudflare/ai-agent/src/shared/prompts/prompt-convo-yes.txt
  • Admin backend: supabase/functions/admin-ai-settings/index.ts
  • Admin UI: src/components/admin/AdminAiSettings.tsx

Non-Goals

  • This spec does not define vehicle extraction behavior.
  • This spec does not define no-intent behavior.
  • This spec does not define AI summary generation behavior.