> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kallglot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Modes

> Understanding the different session modes in Kallglot

# Session Modes

Kallglot supports different session modes for various use cases. Each mode configures how audio is processed and how translation/AI features behave.

## Available Modes

| Mode                        | Use Case                          | Translation     | AI Agent |
| --------------------------- | --------------------------------- | --------------- | -------- |
| `bidirectional_translation` | Customer support across languages | Both directions | No       |
| `assistive_translation`     | Agent assistance with translation | One direction   | No       |
| `ai_agent`                  | Automated voice agent             | Optional        | Yes      |
| `help_chat_voice`           | Voice-enabled help desk           | Optional        | Yes      |

## Bidirectional Translation

The most common mode for multilingual customer support. Both parties hear translated speech in their preferred language.

```mermaid theme={null}
graph LR
    subgraph Customer
        C[German Speaker]
    end

    subgraph Kallglot
        T1[Transcribe DE]
        TR1[Translate to EN]
        TTS1[Speak EN]
        T2[Transcribe EN]
        TR2[Translate to DE]
        TTS2[Speak DE]
    end

    subgraph Agent
        A[English Speaker]
    end

    C -->|German Audio| T1
    T1 --> TR1
    TR1 --> TTS1
    TTS1 -->|English Audio| A

    A -->|English Audio| T2
    T2 --> TR2
    TR2 --> TTS2
    TTS2 -->|German Audio| C
```

### Configuration

```json theme={null}
{
  "mode": "bidirectional_translation",
  "source_language": "de",
  "target_language": "en"
}
```

### Use Cases

* International customer support centers
* Sales calls with foreign customers
* Technical support across languages

### Features

* Real-time speech-to-speech translation
* Dual-channel recording (original + translated)
* Full transcript with translations

## Assistive Translation

The agent hears the original audio while receiving real-time translated subtitles. The customer hears translated audio of the agent's speech.

```mermaid theme={null}
graph LR
    subgraph Customer
        C[German Speaker]
    end

    subgraph Kallglot
        T1[Transcribe DE]
        TR1[Translate to EN]
        T2[Transcribe EN]
        TR2[Translate to DE]
        TTS2[Speak DE]
    end

    subgraph Agent
        A[English Speaker]
        S[Subtitles]
    end

    C -->|German Audio| T1
    T1 -->|Original German| A
    T1 --> TR1
    TR1 -->|English Text| S

    A -->|English Audio| T2
    T2 --> TR2
    TR2 --> TTS2
    TTS2 -->|German Audio| C
```

### Configuration

```json theme={null}
{
  "mode": "assistive_translation",
  "source_language": "de",
  "target_language": "en"
}
```

### Use Cases

* Agents learning a new language
* Compliance requirements for original audio
* Quality assurance with human oversight

### Features

* Agent hears original customer audio
* Real-time translated subtitles for agent
* Customer hears translated agent speech

## AI Agent

An AI-powered voice agent handles the conversation autonomously. The agent uses natural language understanding to respond contextually.

```mermaid theme={null}
graph LR
    subgraph Customer
        C[Customer]
    end

    subgraph Kallglot
        T[Transcribe]
        AI[AI Processing]
        TTS[Text-to-Speech]
    end

    C -->|Audio| T
    T --> AI
    AI --> TTS
    TTS -->|Response Audio| C
```

### Configuration

```json theme={null}
{
  "mode": "ai_agent",
  "source_language": "en",
  "target_language": "en",
  "ai_agent": {
    "system_prompt": "You are a helpful customer service agent for Acme Corp...",
    "voice": "alloy",
    "knowledge_base_id": "kb_01ABC",
    "tools": [
      {
        "name": "lookup_order",
        "description": "Look up an order by order number",
        "parameters": {
          "type": "object",
          "properties": {
            "order_number": { "type": "string" }
          }
        }
      }
    ]
  }
}
```

### Use Cases

* 24/7 automated customer support
* Appointment scheduling
* Order status inquiries
* FAQ handling

### Features

* Natural language understanding
* Custom system prompts
* Knowledge base integration
* Function calling for external integrations
* Handoff to human agents

### Voice Options

| Voice ID  | Description           |
| --------- | --------------------- |
| `alloy`   | Neutral, professional |
| `echo`    | Warm, friendly        |
| `fable`   | Expressive, narrative |
| `onyx`    | Deep, authoritative   |
| `nova`    | Energetic, youthful   |
| `shimmer` | Calm, soothing        |

## Help Chat Voice

A voice-enabled help desk assistant that combines AI chat with voice capabilities. Ideal for embedded help widgets.

### Configuration

```json theme={null}
{
  "mode": "help_chat_voice",
  "source_language": "en",
  "target_language": "en",
  "help_chat": {
    "knowledge_base_id": "kb_01ABC",
    "escalation_enabled": true,
    "escalation_phone": "+14155551234"
  }
}
```

### Use Cases

* In-app help widgets
* Self-service portals
* After-hours support

### Features

* AI-powered answers from knowledge base
* Voice input and output
* Seamless escalation to human agents
* Chat history context

## Comparing Modes

| Feature               | Bidirectional | Assistive | AI Agent | Help Chat |
| --------------------- | ------------- | --------- | -------- | --------- |
| Real-time translation | ✅ Both ways   | ✅ One way | Optional | Optional  |
| Human agent required  | ✅             | ✅         | ❌        | Optional  |
| AI responses          | ❌             | ❌         | ✅        | ✅         |
| Knowledge base        | ❌             | ❌         | ✅        | ✅         |
| Function calling      | ❌             | ❌         | ✅        | ❌         |
| Escalation support    | ❌             | ❌         | ✅        | ✅         |

## Switching Modes

You cannot change the mode of an active session. To switch modes:

1. End the current session
2. Create a new session with the desired mode
3. Reconnect the audio stream

```javascript theme={null}
// End current session
await endKallglotSession(currentSessionId);

// Create new session with different mode
const newSession = await createKallglotSession({
  mode: 'ai_agent',
  // ... other config
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the right mode upfront">
    Determine the session mode based on your use case before creating the session. Mode changes require creating a new session.
  </Accordion>

  <Accordion title="Test AI agents thoroughly">
    For `ai_agent` mode, test your system prompts and tools extensively in a staging environment before going live.
  </Accordion>

  <Accordion title="Configure escalation paths">
    For `ai_agent` and `help_chat_voice` modes, always configure an escalation path to human agents for complex issues.
  </Accordion>

  <Accordion title="Use assistive mode for training">
    Use `assistive_translation` mode to train agents on new languages while maintaining quality.
  </Accordion>
</AccordionGroup>