Idle messages

Overview

Idle messages automatically prompt users during periods of inactivity to maintain engagement and reduce call abandonment. They are set up using Assistant Hooks to trigger on customer silence timeout, and can be configured to say exact messages or use a model-generated message based on the conversation history.

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. Based on the configured timeout periods in customer.speech.timeout hooks, the assistant will trigger the action, which can be configured to say messages to the user.

Configuration

Configure idle messages using Assistant Hooks. Use the customer.speech.timeout hook to send a message when the user is silent for a specified period:

1
import { VapiClient } from "@vapi-ai/server-sdk";
2
3
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
4
5
await client.assistants.create({
6
  name: "Support Assistant",
7
  hooks: [
8
    {
9
      on: "customer.speech.timeout",
10
      options: {
11
        timeoutSeconds: 10,
12
        triggerMaxCount: 3,
13
        triggerResetMode: "onUserSpeech"
14
      },
15
      do: [
16
        {
17
          type: "say",
18
          exact: [
19
            "Are you still there?",
20
            "Can I help you with anything else?",
21
            "I'm here whenever you're ready to continue."
22
          ]
23
        }
24
      ],
25
      name: "idle_message_check"
26
    }
27
  ]
28
});

Configuration options

Timeout and triggering

Message action

Advanced configuration

1
{
2
  "hooks": [
3
    {
4
      "on": "customer.speech.timeout",
5
      "options": { "timeoutSeconds": 10 },
6
      "do": [{ "type": "say", "exact": "Are you still there?" }]
7
    }
8
  ]
9
}

Multilingual support

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

1
// English assistant
2
await client.assistants.create({
3
  name: "EN Support",
4
  hooks: [{
5
    on: "customer.speech.timeout",
6
    options: { timeoutSeconds: 10 },
7
    do: [{ type: "say", exact: [
8
      "Are you still there?",
9
      "Can I help you with anything else?"
10
    ] }]
11
  }]
12
});
13
14
// Spanish assistant
15
await client.assistants.create({
16
  name: "ES Support",
17
  hooks: [{
18
    on: "customer.speech.timeout",
19
    options: { timeoutSeconds: 10 },
20
    do: [{ type: "say", exact: [
21
      "¿Sigues ahí?",
22
      "¿Puedo ayudarte con algo más?"
23
    ] }]
24
  }]
25
});

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:

Troubleshooting

Messages not triggering

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

1
{
2
  "options": {
3
    "triggerMaxCount": 5,
4
    "triggerResetMode": "onUserSpeech"
5
  }
6
}

Common issues and solutions

1
{ "idleTimeoutSeconds": 25 }

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

Limitations

• Generative variability: Using say.prompt produces model-generated text that may vary; use say.exact for strict control
• Trigger limits: triggerMaxCount caps how many times the timeout hook fires per call (1-10)
• Timeout range: timeoutSeconds supports 1-1000 seconds (default ~7.5s); account for processing delays
• Processing delays: Allow 2-3 seconds of audio processing time when choosing timeout values

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