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

# Sessions & Deployment

> Understand sessions and choose how to deploy your agents

## What is a Session?

A **session** is a single conversation between a user and an agent. When a user clicks "Start" or loads your agent, a session begins. The session includes:

* **Real-time video/audio** - WebRTC connection via Daily.co
* **Conversation state** - The ongoing dialogue between user and agent
* **Tool executions** - Any tools the agent calls during the conversation

Sessions end when the user disconnects, closes the tab, or the connection times out.

<Info>
  **Single-Use vs Permanent agents:** Single-Use agents can only have one session—the agent expires after it ends. Permanent agents can have unlimited sessions using the same agent ID.
</Info>

***

## Deployment Options

There are three ways to deploy your agents:

<CardGroup cols={3}>
  <Card title="Hosted Page" icon="globe" href="#option-1-hosted-page">
    Instant deployment via meet.iwy.ai
  </Card>

  <Card title="Embeddable Widgets" icon="code" href="#option-2-embeddable-widgets">
    Drop-in components for your website
  </Card>

  <Card title="Custom Integration" icon="wrench" href="#option-3-custom-integration">
    Full control with the Daily.co SDK
  </Card>
</CardGroup>

***

## Option 1: Hosted Page

The fastest way to deploy—just share a URL.

```
https://meet.iwy.ai/YOUR_AGENT_ID
```

When someone visits this URL with a valid agent ID, a session starts automatically. No code required.

**Use cases:**

* Share a link via email, SMS, or QR code
* Embed in calendar invites
* Quick demos and testing

**Example:**

```
https://meet.iwy.ai/550e8400-e29b-41d4-a716-446655440000
```

<Note>
  Works with both Single-Use and Permanent agent IDs.
</Note>

***

## Option 2: Embeddable Widgets

Drop-in web components that you embed directly in your website. The widgets handle all session management automatically—users just click to start.

**Repository:** [github.com/iwy-ai/live-widgets](https://github.com/iwy-ai/live-widgets)

**npm:** [@iwy/live-widgets](https://www.npmjs.com/package/@iwy/live-widgets)

### Quick Start

Add the script tag and component to your HTML:

```html theme={"dark"}
<!-- The widget component -->
<live-avatar agentid="YOUR_AGENT_ID"></live-avatar>

<!-- Load the widget script -->
<script src="https://unpkg.com/@iwy/live-widgets@latest/dist/live-avatar.min.js"></script>
```

That's it. When a user clicks the widget, a session starts automatically.

### Via npm

```bash theme={"dark"}
npm install @iwy/live-widgets
```

```jsx theme={"dark"}
import '@iwy/live-widgets';

function App() {
  return <live-avatar agentid="YOUR_AGENT_ID"></live-avatar>;
}
```

### Widget Options

| Attribute | Required | Description                                 |
| --------- | -------- | ------------------------------------------- |
| `agentid` | Yes      | Your agent's UUID (Single-Use or Permanent) |

**Use cases:**

* Customer support widget on your website
* Sales agent embedded in product pages
* Interactive demos in documentation

<Tip>
  The widget calls the `/start-agent-session` endpoint automatically when clicked. You don't need to make any API calls yourself.
</Tip>

***

## Option 3: Custom Integration

For full control over the UI and experience, use the `/start-agent-session` endpoint directly with the Daily.co SDK.

### How It Works

1. **Call the API** to get connection credentials
2. **Use Daily.co SDK** to join the room with your own UI
3. **Handle events** for custom behavior

### Step 1: Get Session Credentials

```bash theme={"dark"}
curl -X POST https://api.iwy.ai/v1/start-agent-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_ID"
  }'
```

**Response:**

```json theme={"dark"}
{
  "roomUrl": "https://iwy.daily.co/room-abc123",
  "dailyToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "webLink": "https://app.iwy.ai/call/room-abc123"
}
```

| Field        | Description                               |
| ------------ | ----------------------------------------- |
| `roomUrl`    | Daily.co room URL for SDK connection      |
| `dailyToken` | Authentication token for the room         |
| `webLink`    | Browser-accessible link (no SDK required) |

### Step 2: Connect with Daily.co SDK

**TypeScript/JavaScript:**

```typescript theme={"dark"}
import DailyIframe from '@daily-co/daily-js';

// Create the call frame
const callFrame = DailyIframe.createFrame({
  iframeStyle: {
    width: '100%',
    height: '100%',
  },
});

// Join the session
await callFrame.join({
  url: roomUrl,      // from API response
  token: dailyToken, // from API response
});

// Handle events
callFrame.on('left-meeting', () => {
  console.log('Session ended');
});
```

**React:**

```tsx theme={"dark"}
import { DailyProvider, DailyVideo } from '@daily-co/daily-react';

function VideoSession({ roomUrl, token }) {
  return (
    <DailyProvider url={roomUrl} token={token}>
      <DailyVideo />
    </DailyProvider>
  );
}
```

### Daily.co SDK Resources

| Resource         | Link                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| JavaScript SDK   | [docs.daily.co/reference/daily-js](https://docs.daily.co/reference/daily-js)                     |
| React SDK        | [docs.daily.co/reference/daily-react](https://docs.daily.co/reference/daily-react)               |
| React Native SDK | [docs.daily.co/reference/daily-react-native](https://docs.daily.co/reference/daily-react-native) |
| iOS SDK          | [docs.daily.co/reference/ios](https://docs.daily.co/reference/ios)                               |
| Android SDK      | [docs.daily.co/reference/android](https://docs.daily.co/reference/android)                       |

**Use cases:**

* Custom video UI matching your brand
* Mobile apps (iOS, Android, React Native)
* Advanced features (recording, transcription, custom controls)
* Integration with existing video infrastructure

***

## Comparison

| Feature       | Hosted Page   | Widgets       | Custom Integration |
| ------------- | ------------- | ------------- | ------------------ |
| Setup time    | None          | 5 minutes     | Hours              |
| Custom UI     | No            | Limited       | Full control       |
| Code required | No            | Minimal       | Yes                |
| Mobile apps   | Browser only  | Browser only  | Native SDKs        |
| Branding      | iwy branded   | Customizable  | Fully custom       |
| Best for      | Quick sharing | Website embed | Custom apps        |

***

## Session Management Pipeline

What happens under the hood when a user starts a session?

<img className="block dark:hidden" src="https://mintcdn.com/iwy/G25hY7NOv8_8zjPz/images/backend-control-flow-sequence-diagram-light.svg?fit=max&auto=format&n=G25hY7NOv8_8zjPz&q=85&s=7df092e79ee75efbd23f31688d698ae4" alt="iwy session management pipeline -- light mode" width="1674" height="1836" data-path="images/backend-control-flow-sequence-diagram-light.svg" />

<img className="hidden dark:block" src="https://mintcdn.com/iwy/G25hY7NOv8_8zjPz/images/backend-control-flow-sequence-diagram-dark.svg?fit=max&auto=format&n=G25hY7NOv8_8zjPz&q=85&s=b7fe1dd8fcf6bb60afe2a562839223bc" alt="iwy session management pipeline -- dark mode" width="1674" height="1836" data-path="images/backend-control-flow-sequence-diagram-dark.svg" />

<p style={{textAlign: 'center', fontStyle: 'italic'}}>
  Sequence diagram showing iwy's session management pipeline: agent provisioning, model orchestration, real-time WebRTC streaming, and analytics data flow. © iwy.ai 2025
</p>

### Pipeline Steps

1. **Session Request** - User clicks widget, visits URL, or your app calls the API
2. **Agent Provisioning** - iwy loads the agent configuration
3. **Room Creation** - Daily.co room is provisioned for WebRTC
4. **Model Orchestration** - LLM, STT, TTS, and video models are initialized
5. **WebRTC Connection** - Real-time audio/video stream established
6. **Conversation Loop** - Speech → Text → LLM → Text → Speech → Video
7. **Analytics** - Session data captured for insights
8. **Session End** - Resources released, data persisted

***

## Quick Reference

| Deployment                 | When to Use               | Getting Started             |
| -------------------------- | ------------------------- | --------------------------- |
| `meet.iwy.ai/{id}`         | Share a link, quick demos | Just share the URL          |
| `<live-avatar>` widget     | Embed on website          | Add script + component      |
| `/start-agent-session` API | Custom UI, mobile apps    | Call API + use Daily.co SDK |

***

## Support

Need help? [Contact us](https://www.iwy.ai/contact)