[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:
- The conversation remains stuck in
pendingstatus for several minutes without an AI response. - Because the conversation is still
pending(andbot_handoff!hasn't been triggered), human agents do not see the conversation in their active inbox view. - The customer is left waiting in a silent
pendingstate with neither an AI response nor a human handoff.
Real-World Scenario
- An administrator adds or updates knowledgebase documents in Captain (enqueuing document embedding jobs).
- A customer sends a message on a channel (WhatsApp / Live Chat / Facebook).
- The conversation status is set to
pendingandCaptain::Conversation::ResponseBuilderJobis enqueued. - Due to worker queue contention, the response job waits in line for several minutes behind the document indexing jobs.
- If a job experiences queue latency, delay, or unhandled runner timeout, the conversation stays stuck in
pendingindefinitely, stranding the end user.
Proposed Solution & Enhancements
1. Queue Isolation (Priority Scoping)
- Move
Captain::Conversation::ResponseBuilderJobto acriticalor 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
pendingstatus past a configurable threshold (e.g., 2–3 minutes) without an AI reply or tool execution, automatically triggerbot_handoff!(or transition the conversation toopen). - This guarantees that no end user remains stranded in an unattended
pendingstate even under heavy system load or unexpected job delays.
️ Affected Components
enterprise/app/jobs/captain/conversation/response_builder_job.rbenterprise/app/jobs/captain/documents/response_builder_job.rbenterprise/app/services/captain/assistant/agent_runner_service.rb
Source: chatwoot/chatwoot