Idle messages

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

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.

Configuration

Configure idle messages in your assistant’s messagePlan:

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

Configuration options

Core settings

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
2
const 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
13
const 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

Timing recommendations

Choose timeout duration based on your use case:

Frequency management

Balance engagement with user experience:

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

Troubleshooting

Messages not triggering

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

1
{ "idleTimeoutSeconds": 12 }

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

Common issues and solutions

1
{ "idleTimeoutSeconds": 25 }

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

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:

• Background messages: Add contextual information silently
• Assistant hooks: Handle call events and state changes
• Voice formatting plan: Control speech patterns and delivery