GUIDES

Chat Mode

Configure your agent for text-only conversations with chat mode

Chat mode allows your agents to act as chat agents, ie to have text-only conversations without audio input/output. This is useful for building chat interfaces, testing agents, or when audio is not required.

Overview

When your agent is configured for chat mode or when you want to enforce text-only conversations programmatically, you can use the SDKs with specific configuration options. This guide covers how to implement chat mode across different SDKs.

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:

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

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:

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

Important Notes

Critical: When using chat mode, you must ensure the agent_response event/callback is activated and properly configured. Without this, the agent’s text responses will not be sent or displayed to the user.

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

1const 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
2conversation.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