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

You can configure an agent for text-only mode when creating it via the API. This sets the default behavior for all conversations with that agent.

1
from elevenlabs import ConversationalConfig, ConversationConfig, ElevenLabs
2
3
client = ElevenLabs(
4
    api_key="YOUR_API_KEY",
5
)
6
7
# Create agent with text-only configuration
8
agent = client.conversational_ai.agents.create(
9
    name="My Chat Agent",
10
    conversation_config=ConversationalConfig(
11
        conversation=ConversationConfig(
12
            text_only=True
13
        )
14
    ),
15
)
16
print(agent)

JavaScript SDK

Text-Only Configuration

To use the JavaScript SDK in chat mode with text-only conversations, add the textOnly override to your conversation configuration:

1
const conversation = await Conversation.startSession({
2
  agentId: '<your-agent-id>',
3
  overrides: {
4
    conversation: {
5
      textOnly: true,
6
    },
7
  },
8
});

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

Python SDK

Text-Only Configuration

For the Python SDK, configure the conversation for text-only mode:

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

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
const conversation = await Conversation.startSession({
2
  agentId: '<your-agent-id>',
3
  overrides: {
4
    conversation: {
5
      textOnly: true,
6
    },
7
  },
8
  // Critical: Handle agent responses
9
  onMessage: (message) => {
10
    if (message.type === 'agent_response') {
11
      console.log('Agent:', message.text);
12
      // Display in your UI
13
      displayAgentMessage(message.text);
14
    }
15
  },
16
});

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.sendUserMessage({
3
  text: 'Hello, how can you help me today?',
4
});

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