Barge-In Configuration

Control how users can interrupt the assistant while speaking.

Overview

Barge-in allows users to interrupt the assistant's speech. You can configure barge-in behavior for each speak or audio action.

Configuration

interface BargeInConfig {
  strategy: "none" | "manual" | "minimum_characters";
  minimum_characters?: number; // Default: 3
  allow_after_ms?: number;     // Delay before allowing interruption
}

Strategies

none

Disables barge-in completely. Audio plays fully without interruption.

barge_in: {
  strategy: "none"
}

Use cases:

• Critical information that must be heard
• Legal disclaimers
• Emergency instructions

Example:

return {
  type: "speak",
  session_id: event.session.id,
  text: "This is important information. Please listen carefully.",
  barge_in: {
    strategy: "none",
  },
};

manual

Allows manual barge-in via API only (no automatic detection).

barge_in: {
  strategy: "manual"
}

Use cases:

• Custom interruption logic
• Button-triggered interruption
• External event-based interruption

Example:

return {
  type: "speak",
  session_id: event.session.id,
  text: "Press a button to interrupt.",
  barge_in: {
    strategy: "manual",
  },
};

minimum_characters

Automatically detects barge-in when user speech exceeds character threshold.

barge_in: {
  strategy: "minimum_characters",
  minimum_characters: 5,      // Trigger after 5 characters
  allow_after_ms: 500          // Wait 500ms before allowing interruption
}

Use cases:

• Natural conversation flow
• Customer service scenarios
• Interactive voice menus

Example:

return {
  type: "speak",
  session_id: event.session.id,
  text: "How can I help you today?",
  barge_in: {
    strategy: "minimum_characters",
    minimum_characters: 3,
  },
};

Protection Period

You can add a protection period to prevent interruption during critical parts of speech:

return {
  type: "speak",
  session_id: event.session.id,
  text: "Your account number is 1234567890. Please write this down.",
  barge_in: {
    strategy: "minimum_characters",
    minimum_characters: 10, // Require substantial speech
    allow_after_ms: 2000,    // Protect first 2 seconds
  },
};

Configuration Options

minimum_characters

The minimum number of characters the user must speak before barge-in is triggered.

• Default: 3
• Range: 1 to 100
• Use: Higher values require more speech before interruption

allow_after_ms

Delay in milliseconds before barge-in is allowed. This creates a "protection period" at the start of speech.

• Default: 0 (immediate)
• Range: 0 to 10000 (10 seconds)
• Use: Prevent interruption during critical information

Examples

Natural Conversation

onUserSpeak: async (event) => {
  return {
    type: "speak",
    session_id: event.session.id,
    text: "I can help you with billing, support, or sales. What would you like?",
    barge_in: {
      strategy: "minimum_characters",
      minimum_characters: 3,
    },
  };
}

Critical Information

onUserSpeak: async (event) => {
  return {
    type: "speak",
    session_id: event.session.id,
    text: "Your verification code is 1-2-3-4-5-6. Please write this down.",
    barge_in: {
      strategy: "none", // Don't allow interruption
    },
  };
}

Protected Announcement

onSessionStart: async (event) => {
  return {
    type: "speak",
    session_id: event.session.id,
    text: "Welcome! Your call may be recorded for quality assurance.",
    barge_in: {
      strategy: "minimum_characters",
      minimum_characters: 5,
      allow_after_ms: 3000, // Protect first 3 seconds
    },
  };
}

Best Practices

1. Use none sparingly - Only for truly critical information
2. Default to minimum_characters - Provides natural conversation flow
3. Set protection periods - For important announcements or account numbers
4. Test with users - Find the right balance for your use case

Next Steps

• Action Types - Complete action reference
• API Reference - Full API documentation