> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Simulations

> Test text-based AI agents the same way you test voice agents

## Overview

Chat simulations run persona-driven conversations against text-based AI agents: the same testing primitives you use for voice, applied to text. Roark plays the human side of the chat, sends messages to your agent, and evaluates the resulting transcript against your metrics and checks.

If you've run voice simulations, you already know how chat simulations work. The mental model is identical: a [persona](/documentation/simulation-testing/personas) drives the customer's behavior, a [customer flow](/documentation/simulation-testing/customer-flows) defines the conversation, a [plan](/documentation/simulation-testing/run-plans) ties them together with an agent endpoint, and [metrics](/documentation/metrics/overview) measure the outcome.

***

## Voice vs. Chat Endpoints

Whether a simulation runs as a call or a chat is decided by the **endpoint type** on the agent target. You don't pick a modality separately.

| Modality  | Endpoint types                                |
| :-------- | :-------------------------------------------- |
| **Voice** | Phone, WebRTC, LiveKit                        |
| **Chat**  | WebSocket, ElevenLabs WS, Kore AI, Google CES |

<Note>
  ElevenLabs WS endpoints resolve to **chat**, not voice. To test an ElevenLabs agent over audio, use a Phone endpoint instead.
</Note>

***

## How It's Different from Voice Simulations

Chat simulations reuse every concept from voice simulations, with a few practical differences:

|                         | Voice Simulations                             | Chat Simulations                                 |
| :---------------------- | :-------------------------------------------- | :----------------------------------------------- |
| **Transport**           | Phone, WebRTC, LiveKit audio                  | WebSocket / HTTP text messages                   |
| **Persona output**      | Synthesized speech with accent, gender, pace  | Typed text in the persona's style                |
| **Step types**          | All Scripted steps including Silence and DTMF | Text steps: Customer, Agent, First message       |
| **Conversation record** | Stored as a **call** with audio + transcript  | Stored as a **chat** with the message transcript |

Voice-only step types in Scripted flows (Silence, DTMF, and Voicemail steps in older flows) are skipped automatically when a flow runs against a chat endpoint, so you can reuse existing flows without forking them, and text-relevant steps still execute. [Voicemail testing](/documentation/simulation-testing/voicemail) is voice-only for the same reason: a greeting is audio, so there's nothing for a chat transcript to carry.

***

## What's Shared with Voice Simulations

Everything except the transport layer is shared:

* **Personas**: The attributes that shape text behavior carry over: **language**, **base emotion**, **clarity**, **response timing**, and **disfluencies** (natural false starts, rendered as typed hesitations). Voice-only attributes (accent, gender, speech pace) are simply ignored in a chat.
* **Customer flows**: Both Improv and Scripted flows work for chat. The same variants, agent expectations, and `{{variable}}` values apply.
* **Plans**: Build a chat plan the same way you build a voice one; the only difference is selecting an agent target with a chat endpoint.
* **Variables**: [Variables](/documentation/simulation-testing/variables) resolve identically.
* **Metrics and checks**: System and custom metrics run on chat transcripts, and Pass/Fail checks evaluate the same way. Metrics that only apply to audio (e.g. speech rate, silence duration) are skipped.
* **Schedules**: Chat plans can be [scheduled](/documentation/simulation-testing/schedules) the same way as voice plans.
* **Re-runs and reporting**: Identical experience, with chat results appearing alongside call results in run reports.

Write your flows and personas once, then point them at either a voice endpoint or a chat endpoint depending on what you want to test.

***

## How Chat Simulations Run

<Steps>
  <Step title="Build a plan">
    Attach customer flows, pick metrics and checks, and select an agent target with a **chat endpoint** (see supported providers below).
  </Step>

  <Step title="Roark opens a session">
    For each conversation, Roark establishes a session with your agent over the provider's chat transport. Credentials live on the integration. They're never embedded in the plan.
  </Step>

  <Step title="The persona drives the conversation">
    Roark plays the customer using the persona's language and behavioral attributes, following the flow variant and adapting to whatever your agent actually says.
  </Step>

  <Step title="Transcript is captured and evaluated">
    Every message is recorded as a chat. When the conversation ends, your configured metrics and checks are evaluated against the transcript.
  </Step>
</Steps>

<Note>
  Chat simulations always run outbound-from-Roark: Roark initiates the session against your agent endpoint. The [inbound vs. outbound](/documentation/simulation-testing/inbound-vs-outbound) distinction from voice simulations doesn't apply to chat.
</Note>

***

## Watching Chat Simulations Live

While a run is in progress, chat sessions appear in the run's **Live now** board just like calls. The live transcript and conversation events stream in real time as the persona and your agent exchange messages. The only difference from voice is that there's no audio: the listen-in audio card is hidden for chat sessions.

***

## Supported Providers

Chat simulations require a chat-capable agent endpoint. Provider endpoints are created automatically when you connect a supported integration. You don't need to wire them up manually.

<CardGroup cols={3}>
  <Card title="ElevenLabs" icon="audio-lines" href="/documentation/integrations/elevenlabs">
    Run chat simulations against your ElevenLabs Conversational AI agents.
  </Card>

  <Card title="Google CES" icon="cloud" href="/documentation/integrations/google-ces">
    Run chat simulations against your Google Customer Engagement Suite apps.
  </Card>

  <Card title="Kore AI" icon="bot" href="/documentation/integrations/kore">
    Run chat simulations against your Kore AI Agent Platform apps.
  </Card>
</CardGroup>

You can also target a plain **WebSocket** endpoint for custom text agents. See each provider's page for setup steps and required credentials.

***

## Viewing Chat Results

Completed chat simulations appear in **Simulate → Runs** alongside call results, under the run's SR-{'{n}'} label. Opening a chat shows the full message transcript, persona context, and evaluated metric and check results.

Chats are first-class conversation records in Roark. They show up in reports, dashboards, and [collectors](/documentation/metrics/metric-collectors) the same way calls do.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Personas" icon="users" href="/documentation/simulation-testing/personas">
    Set up the customer side of your chats
  </Card>

  <Card title="Build Customer Flows" icon="book-open" href="/documentation/simulation-testing/customer-flows">
    Design the conversation in Improv or Scripted mode
  </Card>

  <Card title="Connect a Provider" icon="plug" href="/documentation/integrations/overview">
    Pick the chat-capable platform you want to test
  </Card>

  <Card title="Plans and Runs" icon="list-check" href="/documentation/simulation-testing/run-plans">
    Combine everything into a runnable test suite
  </Card>
</CardGroup>