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

# Preview Agent Session

> Start a live preview session to test an agent before assigning a phone number.

Use preview mode to test an agent directly from the dashboard (or your own client) without placing a PSTN call.

## What this endpoint does

`POST /api/start/{agent_id}` creates a temporary preview session and returns connection details:

* `dailyRoom`: temporary room URL
* `dailyToken`: temporary participant token
* `sessionId`: Butter call/session ID (`call_...`)

This is the customer-facing session start flow used by the agent preview UI.

<ParamField path="agent_id" type="string" required>
  Agent ID to preview (format: `agent_...`).
</ParamField>

<ParamField body="createDailyRoom" type="boolean">
  When `true`, requests creation of a room for this preview session.
</ParamField>

<ParamField body="dailyRoomProperties" type="object">
  Optional room configuration passed through to the preview room provider.
</ParamField>

<ParamField body="dailyMeetingTokenProperties" type="object">
  Optional token configuration for the preview participant.
</ParamField>

<ParamField body="body" type="object">
  Optional custom payload forwarded to the preview bot runtime.
</ParamField>

### Response

<ResponseField name="dailyRoom" type="string">
  Preview room URL.
</ResponseField>

<ResponseField name="dailyToken" type="string">
  Preview participant token.
</ResponseField>

<ResponseField name="sessionId" type="string">
  Preview session call ID (`call_...`).
</ResponseField>

<RequestExample>
  ```json Request theme={null}
  {
    "createDailyRoom": true,
    "dailyRoomProperties": {
      "start_video_off": true
    },
    "dailyMeetingTokenProperties": {
      "is_owner": true,
      "user_name": "Preview Tester"
    },
    "body": {
      "test_context": "agent-editor-preview"
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "dailyRoom": "https://your-domain.daily.co/room-name",
    "dailyToken": "eyJhbGciOi...",
    "sessionId": "call_a1b2c3d4e5f6"
  }
  ```
</ResponseExample>

## Offer/Answer testing flow (custom WebRTC clients)

If you are building a custom WebRTC test client, Butter preview also supports an offer/answer exchange:

1. Create an SDP offer from your client.
2. Send the offer to the preview API.
3. Apply the returned SDP answer in your client.
4. Continue ICE candidate exchange until connected.

<Note>
  This docs section intentionally stays at flow level. It does not expose low-level transport internals.
</Note>