Detecting Idle Users
Learn how to detect and respond when users are inactive in conversations
Overview
In conversational applications, it’s important to handle situations where users go silent or inactive. Pipecat’s UserIdleProcessor
helps you detect when users haven’t spoken for a defined period, allowing your bot to respond appropriately.
How It Works
The UserIdleProcessor
monitors user activity and:
- Starts tracking after the first interaction (user or bot speaking)
- Resets a timer whenever the user speaks
- Calls your custom callback function when the user is idle for longer than the timeout period
- Provides a retry counter to track consecutive idle periods
- Allows you to implement escalating responses or gracefully end the conversation
The processor uses speech events (not audio frames) to detect activity, so it requires an active speech-to-text service or a transport with built-in speech detection.
Basic Implementation
Step 1: Create a Handler Function
First, create a callback function that will be triggered when the user is idle:
Step 2: Create the Idle Processor
Initialize the processor with your callback and desired timeout:
Step 3: Add to Your Pipeline
Place the processor after speech detection but before context handling:
Best Practices
- Set appropriate timeouts: Shorter timeouts (5-10 seconds) work well for voice conversations
- Use escalating responses: Start with gentle reminders and gradually become more direct
- Limit retry attempts: After 2-3 unsuccessful attempts, consider ending the conversation gracefully by pushing an
EndFrame
Next Steps
Try the User Idle Example
Explore a complete working example that demonstrates how to detect and respond to user inactivity in Pipecat.
UserIdleProcessor Reference
Read the complete API reference documentation for advanced configuration options and callback patterns.
Implementing idle user detection improves the conversational experience by ensuring your bot can handle periods of user inactivity gracefully, either by prompting for re-engagement or politely ending the conversation when appropriate.