Idle messages

Keep users engaged during conversation pauses

Overview

Idle messages automatically prompt users during periods of inactivity to maintain engagement and reduce call abandonment. They work alongside silence timeout messages to handle conversation flow during calls.

Idle messages help you:

  • Re-engage users who become distracted or experience audio delays
  • Reduce call abandonment rates during silent periods
  • Provide proactive assistance when users hesitate or need guidance

Idle messages are automatically disabled during tool calls and warm transfers to avoid interrupting system processes.

How idle messages work

When a user stops speaking, Vapi starts a timer. After the configured timeout period, it randomly selects and speaks one of your idle messages. This process repeats until either the user responds or the maximum message count is reached.

Detection

Timer starts when user stops speaking

Activation

Random message plays after timeout

Reset

Counter resets when user responds (optional)

Configuration

Configure idle messages in your assistant’s messagePlan:

1import { VapiClient } from "@vapi-ai/server-sdk";
2
3const client = new VapiClient({ token: process.env.VAPI_API_KEY });
4
5const assistant = await client.assistants.create({
6name: "Support Assistant",
7messagePlan: {
8idleMessages: [
9"Are you still there?",
10"Can I help you with anything else?",
11"I'm here whenever you're ready to continue."
12],
13idleTimeoutSeconds: 15,
14idleMessageMaxSpokenCount: 3,
15idleMessageResetCountOnUserSpeechEnabled: true
16}
17});

Configuration options

Core settings

ParameterTypeRangeDefaultDescription
idleMessagesstring[]≤1000 chars eachundefinedArray of messages to randomly select from
idleTimeoutSecondsnumber5-60 seconds10Timeout before triggering first message
idleMessageMaxSpokenCountnumber1-10 messages3Maximum times to repeat messages
idleMessageResetCountOnUserSpeechEnabledboolean-falseReset count when user speaks

Advanced configuration

1{
2 "messagePlan": {
3 "idleMessages": ["Are you still there?"],
4 "idleTimeoutSeconds": 10
5 }
6}

Multilingual support

Handle multiple languages by creating language-specific assistants or dynamically updating messages:

1// English assistant
2const enAssistant = await client.assistants.create({
3 name: "EN Support",
4 messagePlan: {
5 idleMessages: [
6 "Are you still there?",
7 "Can I help you with anything else?"
8 ]
9 }
10});
11
12// Spanish assistant
13const esAssistant = await client.assistants.create({
14 name: "ES Support",
15 messagePlan: {
16 idleMessages: [
17 "¿Sigues ahí?",
18 "¿Puedo ayudarte con algo más?"
19 ]
20 }
21});

Best practices

Message content guidelines

  • Keep messages concise - Users may be distracted, so shorter is better
  • Use encouraging tone - Avoid demanding or impatient language
  • Offer specific help - Guide users toward productive next steps

Good examples: - “Are you still there?” - “Is there anything specific you need help with?” - “I’m here whenever you’re ready to continue.”

Avoid: - “Why aren’t you responding?” - “Hello? Hello? Are you there?” - Long explanations or complex questions

Timing recommendations

Choose timeout duration based on your use case:

Urgent calls

5-10 seconds For transactional or time-sensitive interactions

Support calls

10-20 seconds For general customer service and assistance

Complex topics

20-30 seconds For problem-solving or decision-making conversations

Frequency management

Balance engagement with user experience:

1{
2 "idleMessageMaxSpokenCount": 2,
3 "idleMessageResetCountOnUserSpeechEnabled": true,
4 "idleTimeoutSeconds": 15
5}

Enable idleMessageResetCountOnUserSpeechEnabled to give users multiple chances to engage throughout long conversations.

Troubleshooting

Messages not triggering

1

Verify configuration

Check that idle messages are properly configured:

1const assistant = await client.assistants.get(assistantId);
2console.log('Idle config:', assistant.messagePlan);
2

Check timeout duration

Account for audio processing delays (2-3 seconds):

1{ "idleTimeoutSeconds": 12 }
3

Verify message limits

Ensure the maximum count hasn’t been reached:

1{
2 "idleMessageMaxSpokenCount": 5,
3 "idleMessageResetCountOnUserSpeechEnabled": true
4}

Common issues and solutions

Solution: Increase the timeout duration

1{ "idleTimeoutSeconds": 25 }

Solution: Enable reset on user speech and increase max count

1{
2 "idleMessageMaxSpokenCount": 5,
3 "idleMessageResetCountOnUserSpeechEnabled": true
4}

Solution: This shouldn’t happen - idle messages are automatically disabled during tool calls and transfers. If it persists, contact support.

Limitations

  • Static content: Messages cannot be dynamically generated based on conversation context
  • No context awareness: Messages don’t adapt to the current conversation topic
  • Character limits: Each message is limited to 1000 characters
  • Processing delays: Account for 2-3 seconds of audio processing time in your timeout settings

Next steps

Now that you have idle messages configured: