#15835·chatwoot

[Feature Request / Reliability] Isolate Captain chat response jobs to high-priority queue and add fallback handoff for stuck pending conversations

Author: md-riazCreated Sep 16, 2026Updated Sep 17, 2026
LabelsCaptainFeature

Problem Summary

In production environments utilizing Captain (AI Assistant), real-time conversation response jobs (Captain::Conversation::ResponseBuilderJob) share background worker queues (Sidekiq) with heavy, asynchronous document indexing/embedding jobs (Captain::Documents::ResponseBuilderJob).

When large document updates or batch embeddings are processed, incoming customer messages sit behind these heavy jobs in the worker queue. Consequently:

  1. The conversation remains stuck in pending status for several minutes without an AI response.
  2. Because the conversation is still pending (and bot_handoff! hasn't been triggered), human agents do not see the conversation in their active inbox view.
  3. The customer is left waiting in a silent pending state with neither an AI response nor a human handoff.

Real-World Scenario

  1. An administrator adds or updates knowledgebase documents in Captain (enqueuing document embedding jobs).
  2. A customer sends a message on a channel (WhatsApp / Live Chat / Facebook).
  3. The conversation status is set to pending and Captain::Conversation::ResponseBuilderJob is enqueued.
  4. Due to worker queue contention, the response job waits in line for several minutes behind the document indexing jobs.
  5. If a job experiences queue latency, delay, or unhandled runner timeout, the conversation stays stuck in pending indefinitely, stranding the end user.

Proposed Solution & Enhancements

1. Queue Isolation (Priority Scoping)

  • Move Captain::Conversation::ResponseBuilderJob to a critical or high-priority queue so real-time chat replies take precedence over background document indexing (Captain::Documents::ResponseBuilderJob).

2. Fallback Handoff Timeout Guard

  • Introduce a fallback mechanism or background check: if a conversation remains in pending status past a configurable threshold (e.g., 2–3 minutes) without an AI reply or tool execution, automatically trigger bot_handoff! (or transition the conversation to open).
  • This guarantees that no end user remains stranded in an unattended pending state even under heavy system load or unexpected job delays.

️ Affected Components

  • enterprise/app/jobs/captain/conversation/response_builder_job.rb
  • enterprise/app/jobs/captain/documents/response_builder_job.rb
  • enterprise/app/services/captain/assistant/agent_runner_service.rb