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

# Chatbot

> Conversation state management and message history

The `Chatbot` class manages conversation state, chat history, and system prompt configuration for voice conversations.

## Class: Chatbot

Manages the conversation state machine and preprocesses messages for the LLM.

### Import

```python theme={null}
from unmute.llm.chatbot import Chatbot
```

### Constructor

<ParamField path="__init__" type="method">
  Creates a new Chatbot instance with empty conversation history.

  ```python theme={null}
  chatbot = Chatbot()
  ```
</ParamField>

## Methods

### conversation\_state

<ParamField path="conversation_state" type="method" returns="Literal[&#x22;waiting_for_user&#x22;, &#x22;user_speaking&#x22;, &#x22;bot_speaking&#x22;]">
  Returns the current conversation state.

  **States:**

  * `"waiting_for_user"` - Bot is idle, waiting for user to speak
  * `"user_speaking"` - User is currently speaking
  * `"bot_speaking"` - Bot is generating/speaking a response

  ```python theme={null}
  state = chatbot.conversation_state()
  if state == "bot_speaking":
      print("Bot is currently responding")
  ```
</ParamField>

### add\_chat\_message\_delta

<ParamField path="add_chat_message_delta" type="async method" returns="bool">
  Adds a text delta to the conversation history.

  **Parameters:**

  * `delta` (str) - Text chunk to add
  * `role` (Literal\["user", "assistant"]) - Message role
  * `generating_message_i` (int | None) - Index of message being generated

  **Returns:** `True` if a new message was started, `False` if appending to existing

  ```python theme={null}
  # Add user message
  is_new = await chatbot.add_chat_message_delta("Hello!", role="user", generating_message_i=None)

  # Add assistant response chunks
  await chatbot.add_chat_message_delta("Hi", role="assistant", generating_message_i=0)
  await chatbot.add_chat_message_delta(" there!", role="assistant", generating_message_i=0)
  ```
</ParamField>

### preprocessed\_messages

<ParamField path="preprocessed_messages" type="method" returns="list[dict[str, str]]">
  Returns the conversation history with preprocessing applied.

  Preprocessing includes:

  * Removing interruption markers
  * Removing silence markers
  * Trimming incomplete messages

  ```python theme={null}
  messages = chatbot.preprocessed_messages()
  # [
  #   {"role": "system", "content": "You are a helpful assistant."},
  #   {"role": "user", "content": "Hello!"},
  #   {"role": "assistant", "content": "Hi there!"}
  # ]
  ```
</ParamField>

### set\_instructions

<ParamField path="set_instructions" type="method">
  Sets the system prompt instructions for the conversation.

  **Parameters:**

  * `instructions` (Instructions) - Instruction configuration object

  ```python theme={null}
  from unmute.llm.system_prompt import SmalltalkInstructions

  instructions = SmalltalkInstructions(language="en")
  chatbot.set_instructions(instructions)
  ```
</ParamField>

### get\_instructions

<ParamField path="get_instructions" type="method" returns="Instructions | None">
  Returns the current instructions configuration.

  ```python theme={null}
  instructions = chatbot.get_instructions()
  if instructions:
      print(f"Using instruction type: {instructions.type}")
  ```
</ParamField>

### get\_system\_prompt

<ParamField path="get_system_prompt" type="method" returns="str">
  Generates the system prompt text from the current instructions.

  ```python theme={null}
  system_prompt = chatbot.get_system_prompt()
  print(system_prompt)  # "You are a friendly conversational AI..."
  ```
</ParamField>

### last\_message

<ParamField path="last_message" type="method" returns="str | None">
  Returns the content of the last message with the specified role.

  **Parameters:**

  * `role` (str) - Role to search for ("user" or "assistant")

  ```python theme={null}
  last_user_msg = chatbot.last_message("user")
  last_bot_msg = chatbot.last_message("assistant")
  ```
</ParamField>

## Conversation State Machine

The Chatbot tracks conversation state based on message history:

```mermaid theme={null}
stateDiagram-v2
    [*] --> waiting_for_user
    waiting_for_user --> user_speaking: User starts speaking
    user_speaking --> bot_speaking: User finishes, bot responds
    bot_speaking --> waiting_for_user: Bot finishes response
    bot_speaking --> user_speaking: User interrupts bot
```

## Instructions Types

The Chatbot supports multiple instruction types defined in `unmute.llm.system_prompt`:

* **SmalltalkInstructions** - Casual conversation
* **ConstantInstructions** - Fixed system prompt text
* **QuizShowInstructions** - Quiz game personality
* **GuessAnimalInstructions** - Animal guessing game
* **NewsInstructions** - News reading personality
* **UnmuteExplanationInstructions** - Explains how Unmute works

See [Voices and Characters](/guides/voices-and-characters) for details on configuring instructions.

## Usage Example

```python theme={null}
from unmute.llm.chatbot import Chatbot
from unmute.llm.system_prompt import SmalltalkInstructions

# Create chatbot with smalltalk personality
chatbot = Chatbot()
chatbot.set_instructions(SmalltalkInstructions(language="en"))

# Simulate conversation
await chatbot.add_chat_message_delta("Hi there!", role="user", generating_message_i=None)
await chatbot.add_chat_message_delta("Hello! ", role="assistant", generating_message_i=0)
await chatbot.add_chat_message_delta("How can I help?", role="assistant", generating_message_i=0)

# Get conversation state
state = chatbot.conversation_state()  # "bot_speaking"

# Get processed messages for LLM
messages = chatbot.preprocessed_messages()
```

## Integration with UnmuteHandler

The Chatbot is used internally by `UnmuteHandler` to manage conversation state:

```python theme={null}
# UnmuteHandler uses Chatbot internally
handler = UnmuteHandler()
# handler.chatbot manages the conversation
```

See [UnmuteHandler](/api/python/unmute-handler) for the main orchestration class.

## Related

* [UnmuteHandler](/api/python/unmute-handler) - Main conversation orchestrator
* [LLM Utils](/api/python/llm-utils) - LLM integration utilities
* [Voices and Characters](/guides/voices-and-characters) - Configure system prompts


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.