> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Modo de chat

> **Info**
>
> O modo de chat permite que seus agentes atuem como agentes de chat, ou seja, tenham conversas apenas por
> texto, sem entrada ou saída de áudio. Isso é útil para criar interfaces de chat, testar agentes ou quando
> não é necessário usar áudio.

## Visão geral

Há duas formas principais de ativar o modo de chat:

1. **Configuração do agente**: Configure seu agente para o modo apenas texto ao criá-lo pela API
2. **Substituições em tempo de execução**: Use substituições do SDK para impor conversas apenas por texto de forma programática

Este guia aborda as duas abordagens e como implementar o modo de chat em diferentes SDKs.

## Criando agentes apenas de texto

Configure um agente para o modo apenas texto a fim de torná-lo o padrão para todas as conversas com esse agente.

#### Atualizar pelo painel

Abra seu agente no painel, acesse a aba **Advanced** e ative a opção **Text only**. Salve suas alterações.

#### Atualizar pela CLI

#### Baixar a configuração do agente

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### Editar \`agent_configs/\<agent-name>.json\`

Defina `conversation_config.conversation.text_only`:

```json
{
  "conversation_config": {
    "conversation": {
      "text_only": true
    }
  }
}
```

#### Enviar suas alterações

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Atualizar pela API

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "conversation": {"text_only": True},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    conversation: { textOnly: true },
  },
});
```

> **Info**
>
> Para ver a referência completa da API e todas as opções de configuração disponíveis, consulte o [campo text only na documentação da API Create Agent ](/docs/pt/api-reference/agents/create#request.body.conversation_config.conversation.text_only).

## Substituições em tempo de execução para o modo apenas texto

Para ativar o modo de chat em tempo de execução usando substituições (em vez de configurá-lo no nível do agente), você pode usar a substituição `textOnly` na configuração da conversa:

```python
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData

# Configure for text-only mode with proper structure
conversation_override = {
    "conversation": {
        "text_only": True
    }
}

config = ConversationInitiationData(
    conversation_config_override=conversation_override
)

conversation = Conversation(
    elevenlabs,
    agent_id,
    requires_auth=bool(api_key),
    config=config,
    # Important: Ensure agent_response callback is set
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
)

conversation.start_session()
```

```javascript
const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  overrides: {
    conversation: {
      textOnly: true,
    },
  },
});
```

Essa configuração garante que:

* Nenhuma entrada ou saída de áudio seja usada
* Toda a comunicação ocorra por mensagens de texto
* A conversa funcione no modo de interface semelhante a um chat

## Observações importantes

> **Warning**
>
> **Crítico**: Ao usar o modo de chat, você deve garantir que o evento/callback `agent_response` esteja
> ativado e configurado corretamente. Sem isso, as respostas de texto do agente não serão enviadas nem
> exibidas ao usuário.

> **Info**
>
> **Substituições de segurança**: Ao usar substituições em tempo de execução (e não uma configuração no nível do agente), você deve
> ativar as substituições de conversa nas configurações de segurança do seu agente. Acesse a aba
> **Security** do seu agente e ative as substituições apropriadas. Para mais detalhes, consulte a [documentação sobre substituições ](/docs/pt/eleven-agents/customization/personalization/overrides).

### Requisitos principais

1. **Evento de resposta do agente**: Sempre configure o callback ou manipulador de eventos `agent_response` para receber e exibir as mensagens de texto do agente.

2. **Configuração do agente**: Se seu agente estiver definido especificamente para o modo de chat nas configurações do agente, ele usará automaticamente conversas apenas por texto sem exigir a substituição.

3. **Sem interface de áudio**: Ao usar o modo apenas texto, não é necessário configurar interfaces de áudio nem solicitar permissões de microfone.

### Exemplo: como lidar com respostas do agente

```python
def handle_agent_response(response):
    """Critical handler for displaying agent messages"""
    print(f"Agent: {response}")  # Update your UI with the response
    update_chat_ui(response)

config = ConversationInitiationData(
    conversation_config_override={"conversation": {"text_only": True}}
)

conversation = Conversation(
  elevenlabs,
  agent_id,
  config=config,
  callback_agent_response=handle_agent_response,
)

conversation.start_session()
```

```javascript
const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  overrides: {
    conversation: {
      textOnly: true,
    },
  },
  // Critical: Handle agent responses
  onMessage: (message) => {
    if (message.type === "agent_response") {
      console.log("Agent:", message.text);
      // Display in your UI
      displayAgentMessage(message.text);
    }
  },
});
```

## Enviando mensagens de texto

No modo de chat, você precisará enviar mensagens do usuário de forma programática, em vez de enviá-las por áudio:

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

```javascript
// Send a text message to the agent
conversation.sendUserMessage({
  text: "Hello, how can you help me today?",
});
```

## Benefícios de concorrência

O modo de chat oferece vantagens significativas de concorrência em relação às conversas por voz:

* **Limites maiores**: Conversas apenas por chat têm limites de concorrência 25 vezes maiores que conversas por voz
* **Pool separado**: Conversas por texto usam um pool de concorrência dedicado, independente dos limites de conversas por voz
* **Escalabilidade**: Ideal para aplicações de alto volume, como suporte ao cliente, chatbots ou testes automatizados

| Plano      | Concorrência de voz | Concorrência apenas por chat |
| ---------- | ------------------- | ---------------------------- |
| Grátis     | 4                   | 100                          |
| Starter    | 6                   | 150                          |
| Creator    | 10                  | 250                          |
| Pro        | 20                  | 500                          |
| Scale      | 30                  | 750                          |
| Business   | 30                  | 750                          |
| Enterprise | Maior               | Maior (25x)                  |

> **Note**
>
> Durante o início da conexão, as conversas apenas por chat são verificadas inicialmente em relação ao seu limite total
> de concorrência durante o processo de handshake e, após o estabelecimento da conexão, são transferidas para o pool
> separado de concorrência apenas por chat.

## Casos de uso

O modo de chat é ideal para:

* **Interfaces de chat**: Criar UIs de chat tradicionais sem voz
* **Testes**: Testar a lógica do agente sem dependências de áudio
* **Acessibilidade**: Oferecer alternativas baseadas em texto aos usuários
* **Ambientes silenciosos**: Quando entrada ou saída de áudio não é apropriada
* **Testes de integração**: Testes automatizados de conversas de agentes

## Solução de problemas

### Agente não responde

Se as respostas do agente não estiverem aparecendo:

1. Verifique se o callback `agent_response` está configurado corretamente
2. Verifique se o agente está configurado para o modo de chat ou se a substituição `textOnly` está definida
3. Certifique-se de que a conexão WebSocket foi estabelecida com sucesso

## Próximas etapas

* Saiba mais sobre [como personalizar o comportamento do agente](/docs/pt/eleven-agents/customization/llm)
* Explore [eventos de cliente](/docs/pt/eleven-agents/customization/events/client-events) para interações avançadas
* Consulte a [configuração de autenticação](/docs/pt/eleven-agents/customization/authentication) para conversas seguras