How-to

User idle handling

Automatically prompt silent users and gracefully end calls after repeated inactivity.

Overview

When a user goes silent during a call, the idle handling system detects the inactivity and takes action — speaking a prompt message, retrying, and eventually ending the call if the user remains unresponsive.

UserIdleHandlingConfig fields

Field	Type	Default	Description
`enabled`	`bool`	`false`	Enable or disable idle detection.
`timeout`	`float`	`5.0`	Seconds of user silence before triggering idle handling.
`idle_message`	`str`	—	Message the bot speaks when the user is idle.
`max_retries`	`int`	`3`	Maximum number of idle prompts before ending the call.

How it works

User stops speaking.
Idle timer starts counting (configured by timeout).
After timeout seconds of silence, the bot speaks the idle_message.
The idle counter increments.
If the user responds, the counter resets to zero and the conversation continues normally.
If the user stays silent, steps 2–4 repeat.
After max_retries consecutive idle cycles, the call ends automatically via end_conversation.

Counter reset

Any user speech resets the idle counter to zero. The user only needs to speak once to prevent the call from ending — it doesn’t need to be a long response.

JSON example

json

{
  "configurations": {
    "user_idle_configuration": {
      "enabled": true,
      "timeout": 5.0,
      "idle_message": "Are you still there? I'm happy to continue whenever you're ready.",
      "max_retries": 3
    }
  }
}

Configuration tips

Scenario	Timeout	Max Retries	Idle Message
Quick surveys	`3.0`	`2`	“Are you still there?”
Customer support	`5.0`	`3`	“I’m here whenever you’re ready to continue.”
Complex forms	`8.0`	`4`	“Take your time. Let me know when you’re ready.”
Sales calls	`5.0`	`3`	“I’d love to help further. Are you still on the line?”

Short timeouts

Avoid setting timeout below 3.0 seconds. Users often pause to think, check information, or multitask. Too-short timeouts feel aggressive and hurt the user experience.

Disabling idle handling

To disable idle handling, either omit the user_idle_configuration field entirely or set enabled to false:

json

{
  "configurations": {
    "user_idle_configuration": {
      "enabled": false
    }
  }
}

Was this helpful?

Edit on GitHub