> ## 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.

# roark agent conversation create

> Start a conversation with an agent

Starts a voice conversation (`modality: voice`) or chat (`modality: chat`) with this Roark-hosted agent and returns its id right away. `channel: web` is a conversation in a browser on your site. Call this endpoint from your server, never the browser: it needs your API key. Give the page only `web.clientToken`; the web SDK spends it to join from one of `allowedOrigins` before `web.clientTokenExpiresAt`. Read it back with `GET /v1/conversation/{conversationId}` straight away: `PENDING` until the browser joins, `IN_PROGRESS`, then `ENDED`. One nobody joins ends without ever starting and is never billed. Starting a voice conversation needs `call:create`, a chat `chat:create`, and the agent a published version that takes that kind.

```bash Synopsis theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark agent conversation create <agent-id> [options]
```

> [!NOTE]
>
> Calls `POST /v1/agent/{agentId}/conversations`

## Arguments

**agent-id** `string` *required*

The agent-id.

## Options

**--modality** `string` *required*

`voice` or `chat`. The agent must have that modality turned on. One of `voice`, `chat`, `call`

**--channel** `string` *required*

How it is reached. `web`: in a browser on one of `allowedOrigins`, joined with the web SDK. One of `web`

**--allowed-origins** `array` *required*

The origins your page may join from, exactly as the browser sends them: https only (http on localhost for development), no paths or wildcards. Repeatable.

**--client-token-ttl-seconds** `integer`

How long the browser has to join, in seconds. Default 120.

## Example

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark agent conversation create <agent-id> --modality <value> --channel <value> --allowed-origins <value>
```

Every command also takes the [global options](https://docs.roark.ai/cli-reference/overview.md#global-options) and sets one
of the [exit codes](https://docs.roark.ai/cli-reference/overview.md#exit-codes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.