> ## 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 let you run scripted, 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.

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

***

## How It's Different from Call Simulations

Chat simulations reuse every concept from call simulations, with three practical differences:

|                         | Call Simulations                                  | Chat Simulations                                             |
| :---------------------- | :------------------------------------------------ | :----------------------------------------------------------- |
| **Transport**           | Phone, SIP, WebRTC, LiveKit, ElevenLabs WS audio  | HTTP / WebSocket text messages                               |
| **Persona output**      | Synthesized speech with accent, pace, gender      | Typed text in the persona's voice                            |
| **Step types**          | All step types including silence, DTMF, voicemail | Text-only: customer turn, agent turn, customer first message |
| **Conversation record** | Stored as a **call** with audio + transcript      | Stored as a **chat** with the message transcript             |

Voice-only step types (`CUSTOMER_SILENCE`, `CUSTOMER_DTMF`, `VOICEMAIL`) are filtered out automatically when a scenario runs against a chat endpoint, so you can reuse existing scenarios without having to fork them — text-relevant steps still execute, voice-only ones are skipped.

***

## What's Shared with Call Simulations

Everything except the transport layer is shared. Specifically:

* **Personas** — Every persona attribute that affects text behavior carries over: language, secondary language and code-switching, base emotion, intent clarity, confirmation style, memory reliability, disfluencies, backstory, custom properties. Voice-only attributes (voice ID, accent, speaking pace) are simply ignored when the persona is used in a chat simulation.
* **Scenarios** — The same scenario step structure, branch points, and template variables work for both modalities.
* **Run plans** — Build a chat run plan the same way you build a voice one; the only difference is selecting a chat-capable agent endpoint.
* **Variables** — [Template variables](/documentation/simulation-testing/variables) resolve identically.
* **Metrics & policies** — System and custom metrics run on chat transcripts. Metric definitions that declare support for the `chat` conversation type are eligible; voice-specific metrics (e.g. speech-rate, silence-duration) are skipped.
* **Schedules** — Chat run plans can be scheduled the same way as voice run plans.
* **Re-runs and reporting** — Identical UX, with chat results appearing alongside call results in run summaries.

In other words: write your scenarios 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 run plan">
    Select scenarios, personas, metrics, and a **chat-capable agent endpoint** (see supported providers below).
  </Step>

  <Step title="Roark opens a session">
    For each test case, Roark establishes a session with your agent — over WebSocket for ElevenLabs, over HTTP for Kore AI and Google CES. Credentials live on the integration and are exchanged or minted at run time; they are never embedded in the run plan.
  </Step>

  <Step title="Persona drives the conversation">
    Roark plays the human side using the persona's writing style, language, and behavioral attributes. It follows the scenario step-by-step, adapting to whatever your agent actually says.
  </Step>

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

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

***

## Supported Providers

Chat simulations require a chat-capable [agent endpoint](/documentation/integrations/overview). The endpoint is created automatically when you connect a supported integration — you don't need to wire it up manually.

<CardGroup cols={3}>
  <Card title="ElevenLabs" icon="volume-2" 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>

See each provider's page for setup steps and required credentials.

***

## Viewing Chat Results

Completed chat simulations appear in **Simulations → Runs** alongside call results. Clicking into a chat opens the conversation transcript view with the full message history, persona context, scenario step alignment, and any evaluated metric values.

Chats are first-class conversation records in Roark — they show up in reports, dashboards, and metric collection jobs 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 Scenarios" icon="book-open" href="/documentation/simulation-testing/scenarios">
    Design the conversation flow
  </Card>

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

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