Chat Mode

Overview

There are two main ways to enable chat mode:

1. Agent Configuration: Configure your agent for text-only mode when creating it via the API
2. Runtime Overrides: Use SDK overrides to enforce text-only conversations programmatically

This guide covers both approaches and how to implement chat mode across different SDKs.

Creating Text-Only Agents

Configure an agent for text-only mode to make it the default for every conversation with that agent.

Runtime Overrides for Text-Only Mode

To enable chat mode at runtime using overrides (rather than configuring at the agent level), you can use the textOnly override in your conversation configuration:

1
from elevenlabs.client import ElevenLabs
2
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
3
4
# Configure for text-only mode with proper structure
5
conversation_override = {
6
    "conversation": {
7
        "text_only": True
8
    }
9
}
10
11
config = ConversationInitiationData(
12
    conversation_config_override=conversation_override
13
)
14
15
conversation = Conversation(
16
    elevenlabs,
17
    agent_id,
18
    requires_auth=bool(api_key),
19
    config=config,
20
    # Important: Ensure agent_response callback is set
21
    callback_agent_response=lambda response: print(f"Agent: {response}"),
22
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
23
)
24
25
conversation.start_session()

This configuration ensures that:

• No audio input/output is used
• All communication happens through text messages
• The conversation operates in a chat-like interface mode

Important Notes

Key Requirements

1. Agent Response Event: Always configure the agent_response callback or event handler to receive and display the agent’s text messages.

2. Agent Configuration: If your agent is specifically set to chat mode in the agent settings, it will automatically use text-only conversations without requiring the override.

3. No Audio Interface: When using text-only mode, you don’t need to configure audio interfaces or request microphone permissions.

Example: Handling Agent Responses

1
def handle_agent_response(response):
2
    """Critical handler for displaying agent messages"""
3
    print(f"Agent: {response}")  # Update your UI with the response
4
    update_chat_ui(response)
5
6
config = ConversationInitiationData(
7
    conversation_config_override={"conversation": {"text_only": True}}
8
)
9
10
conversation = Conversation(
11
  elevenlabs,
12
  agent_id,
13
  config=config,
14
  callback_agent_response=handle_agent_response,
15
)
16
17
conversation.start_session()

Sending Text Messages

In chat mode, you’ll need to send user messages programmatically instead of through audio:

1
# Send a text message to the agent
2
conversation.send_user_message("Hello, how can you help me today?")

Concurrency Benefits

Chat mode provides significant concurrency advantages over voice conversations:

• Higher Limits: Chat-only conversations have 25x higher concurrency limits than voice conversations
• Separate Pool: Text conversations use a dedicated concurrency pool, independent of voice conversation limits
• Scalability: Ideal for high-throughput applications like customer support, chatbots, or automated testing

Use Cases

Chat mode is ideal for:

• Chat Interfaces: Building traditional chat UIs without voice
• Testing: Testing agent logic without audio dependencies
• Accessibility: Providing text-based alternatives for users
• Silent Environments: When audio input/output is not appropriate
• Integration Testing: Automated testing of agent conversations

Troubleshooting

Agent Not Responding

If the agent’s responses are not appearing:

1. Verify the agent_response callback is properly configured
2. Check that the agent is configured for chat mode or the textOnly override is set
3. Ensure the WebSocket connection is established successfully

Next Steps

• Learn about customizing agent behavior
• Explore client events for advanced interactions
• See authentication setup for secure conversations