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

# Iframe Integration

> Embed ToughTongue AI in your application

Drop-in widget for any web application. HTTPS required for microphone access.

## Basic Embed

```html theme={null}
<iframe
  src="https://app.toughtongueai.com/embed/SCENARIO_ID"
  width="100%"
  height="600px"
  allow="microphone"
></iframe>
```

***

## Embed Variants

| Variant     | URL                          | Use case                        |
| ----------- | ---------------------------- | ------------------------------- |
| **Full**    | `/embed/SCENARIO_ID`         | Complete UI with login, results |
| **Basic**   | `/embed/basic/SCENARIO_ID`   | Conversation only               |
| **Minimal** | `/embed/minimal/SCENARIO_ID` | Mic button only                 |

***

## URL Parameters

### Visual

| Param           | Values                                | Example                      |
| --------------- | ------------------------------------- | ---------------------------- |
| `color`         | `violet-500`, `blue-500`, `green-500` | `?color=violet-500`          |
| `bg`            | `white`, `black`, hex                 | `?bg=black`                  |
| `showPulse`     | `true`, `false`                       | `?showPulse=false`           |
| `hidePoweredBy` | `true`, `false`                       | `?hidePoweredBy=true` (Pro+) |

### User

| Param       | Type   | Example                       |
| ----------- | ------ | ----------------------------- |
| `userName`  | string | `?userName=John%20Doe`        |
| `userEmail` | string | `?userEmail=john@example.com` |

### Behavior

| Param          | Type    | Example              |
| -------------- | ------- | -------------------- |
| `skipPrecheck` | boolean | `?skipPrecheck=true` |
| `autoStart`    | boolean | `?autoStart=true`    |

**Combined:**

```
/embed/SCENARIO_ID?color=violet-500&bg=black&userName=John&autoStart=true
```

***

## Event Handling

Listen for session events:

```javascript theme={null}
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.toughtongueai.com') return;
  
  const { event: type, sessionId } = event.data;
  
  if (type === 'onStart') {
    console.log('Session started:', sessionId);
  }
  
  if (type === 'onStop') {
    console.log('Session ended:', sessionId);
    // Fetch analysis via your backend
    fetchAnalysis(sessionId);
  }
});
```

**Events:**

| Event          | When                       |
| -------------- | -------------------------- |
| `onStart`      | Conversation begins        |
| `onStop`       | Conversation ends normally |
| `onTerminated` | Unexpected end             |

**Payload:**

```typescript theme={null}
interface IframeEvent {
  event: 'onStart' | 'onStop' | 'onTerminated';
  sessionId: string;
  timestamp: number;
}
```

***

## React Example

```jsx theme={null}
import { useEffect, useState } from 'react';

export default function Practice({ scenarioId }) {
  const [sessionId, setSessionId] = useState(null);
  
  useEffect(() => {
    const handler = (event) => {
      if (event.origin !== 'https://app.toughtongueai.com') return;
      
      if (event.data.event === 'onStart') {
        setSessionId(event.data.sessionId);
      }
      if (event.data.event === 'onStop') {
        window.location = `/results/${event.data.sessionId}`;
      }
    };
    
    window.addEventListener('message', handler);
    return () => window.removeEventListener('message', handler);
  }, []);
  
  return (
    <iframe
      src={`https://app.toughtongueai.com/embed/${scenarioId}?bg=black`}
      width="100%"
      height="600px"
      allow="microphone"
    />
  );
}
```

***

## Responsive Container

```css theme={null}
.iframe-container {
  position: relative;
  width: 100%;
  padding-bottom: 75%;
  height: 0;
}

.iframe-container iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  border: 0;
}
```

***

## Security

<AccordionGroup>
  <Accordion title="Verify origin">
    Always check `event.origin` before processing messages.
  </Accordion>

  <Accordion title="CSP headers">
    `Content-Security-Policy: frame-src https://app.toughtongueai.com;`
  </Accordion>

  <Accordion title="HTTPS only">
    Microphone requires HTTPS (localhost works for dev).
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

| Issue             | Fix                                                    |
| ----------------- | ------------------------------------------------------ |
| Mic not working   | Check HTTPS, browser permissions, `allow="microphone"` |
| Iframe blank      | Verify scenario ID, check `is_public=true`             |
| Events not firing | Check origin filter, ensure listener added before load |

**Next:** [REST API →](/developer/integration/api)