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

# Choose Your Integration

> Choose the right integration method for embedding Corti Assistant into your application

Corti Assistant is a full-featured clinical AI application that can be embedded directly into your healthcare application. It provides ambient documentation, dictation, clinical decision support, and more—all accessible through a programmable interface.

<Tip>
  **Most common integration pattern:** C# desktop application → WebView → localhost HTML page → Web Component. This approach is used by most integrators and provides full control from your native application while leveraging web technologies for the UI layer.
</Tip>

<Tip>
  **Ready to start building?** Check out the [Web Component examples on GitHub](https://github.com/corticph/corti-examples/tree/main/embedded-assistant) to see complete React and vanilla TypeScript implementations. The Web Component is the recommended integration method and provides the best developer experience.
</Tip>

***

## Integration architecture

When you embed Corti Assistant, you're integrating a complete application into your own. This embedded Assistant communicates with your application through one of three integration methods:

```mermaid theme={null}
graph LR
    A[Your Application] -->|Integration Layer| B[Corti Assistant]
    B -->|Clinical Data| C[Corti Platform]

    style A fill:#f9f9f9,stroke:#333,stroke-width:2px
    style B fill:#e8f4f8,stroke:#0066cc,stroke-width:2px
    style C fill:#f0f0f0,stroke:#666,stroke-width:2px
```

Your integration layer handles:

* **Authentication** - Managing user sessions with OAuth2 tokens
* **API Communication** - Creating interactions, generating documents, controlling recording
* **Event Handling** - Receiving updates about interactions, documents, and user actions
* **UI Embedding** - Displaying the Assistant interface in your application

***

## Three integration methods

Corti provides three ways to embed the Assistant, each optimized for different architectural needs:

### Quick decision guide

<Frame>
  ```mermaid theme={null}
  graph TD
    Start[Choose Integration Method] --> Q1{Starting a<br/>new integration?}
    
    Q1 -->|Yes| WebComp[✅ Web Component<br/>Modern, recommended approach]
    Q1 -->|No| Q2{Already using<br/>postMessage?}
    
    Q2 -->|Yes| PostMsg[PostMessage API<br/>Continue with existing implementation]
    Q2 -->|No| Q3{Same origin<br/>scenario?}
    
    Q3 -->|Yes| WindowAPI[Window API<br/>Direct API access]
    Q3 -->|No| WebComp2[✅ Web Component<br/>Cross-origin support]
    
    style WebComp fill:#d4edda,stroke:#28a745,stroke-width:2px
    style WebComp2 fill:#d4edda,stroke:#28a745,stroke-width:2px
    style PostMsg fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style WindowAPI fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px
  ```
</Frame>

### Comparison table

Choose your integration method based on your architectural requirements:

|                          |              Web Component             |              PostMessage             |             Window API             |
| :----------------------- | :------------------------------------: | :----------------------------------: | :--------------------------------: |
| **Recommended For**      |  Native apps (C#) + WebView, web apps  | Existing postMessage implementations | Same-origin / direct URL embedding |
| **Native App Support**   | ✅ Yes (C#, .NET, Electron via WebView) |          ✅ Yes (via WebView)         |         ⚠️ Same-origin only        |
| **Framework Support**    |   Universal (React, Vue, Angular...)   |               Universal              |    Universal (same-origin only)    |
| **Cross-Origin Support** |                  ✅ Yes                 |                 ✅ Yes                |       ❌ No (same-origin only)      |
| **Type Safety**          |             Full TypeScript            |        Manual typing required        |           Full TypeScript          |
| **API Style**            |          Promise-based methods         |     postMessage request/response     |        Promise-based methods       |
| **Event Handling**       |         Native addEventListener        |      Manual postMessage parsing      |       Native addEventListener      |
| **Ease of Use**          |                   5/5                  |                  3/5                 |                 4/5                |
| **React Support**        |       Built-in hooks & components      |         Manual implementation        |        Manual implementation       |
| **Setup Complexity**     |           Install NPM package          |   Create iframe + message handlers   |   Load script + direct API access  |
| **iframe Management**    |                Automatic               |                Manual                |      Manual (if using iframe)      |

***

### Web Component (recommended)

<Frame>
  ```mermaid theme={null}
  graph TB
    subgraph "Path 1: Web Applications"
        WA[React / Vue / Angular<br/>or any web framework]
    end
    
    subgraph "Path 2: Native Applications"
        NA[C# / .NET / Electron<br/>Desktop Application]
        NW[WebView Control<br/>loads HTML page]
        NA -->|hosts| NW
    end
    
    subgraph "Integration Layer"
        B["&lt;corti-embedded&gt;<br/>Web Component"]
        C[Event Listeners]
    end
    
    subgraph "Corti Assistant"
        D[Assistant Interface]
        E[Corti Platform APIs]
    end
    
    WA -->|import & render| B
    NW -->|import & render| B
    B <-->|cross-origin iframe| D
    D <--> E
    B -->|events| C
    
    style WA fill:#e8f4f8,stroke:#0066cc,stroke-width:2px
    style NA fill:#e8d4f8,stroke:#8b5cf6,stroke-width:2px
    style NW fill:#f3e8ff,stroke:#8b5cf6,stroke-width:1px
    style B fill:#d4edda,stroke:#28a745,stroke-width:2px
    style D fill:#e8f4f8,stroke:#0066cc,stroke-width:2px
  ```
</Frame>

A modern, framework-agnostic custom HTML element that wraps the Assistant in a cross-origin iframe. The Web Component handles all postMessage complexity internally and provides a clean TypeScript API.

**Works for both:**

* **Web applications** - React, Vue, Angular, or any framework (including server-rendered pages)
* **Native applications** - C#, .NET, Electron with WebView controls loading a local HTML page

**Best for:**

* Native desktop applications (C#, .NET, Electron) with WebView controls
* Web applications using React, Vue, Angular, or any modern framework
* Mobile applications with WebView components
* New integrations starting from scratch
* Teams that want TypeScript support and native event handling
* Cross-origin scenarios (different domains)

**Architecture highlights:**

* Standard Web Component that works everywhere
* Built-in React hooks and components for optimal DX
* Automatic iframe communication handling
* Promise-based API with TypeScript definitions

<Card title="Web Component Integration Guide" icon="puzzle-piece" horizontal href="/assistant/web-component-api">
  Learn how to integrate using the Web Component API
</Card>

***

### PostMessage API

<Frame>
  ```mermaid theme={null}
  graph TB
    subgraph "Your Application"
        A[Parent Window/Frame]
        B[Manual iframe Management]
        C[Custom postMessage Handler]
    end
    
    subgraph "Corti Assistant"
        D[Assistant Interface]
        E[Corti Platform APIs]
    end
    
    A -->|Create & Mount| B
    B <-->|postMessage Protocol| D
    D <--> E
    D -->|postMessage Events| C
    
    style B fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style D fill:#e8f4f8,stroke:#0066cc,stroke-width:2px
  ```
</Frame>

Direct iframe integration where you manually manage the iframe element and communicate via browser's postMessage API. This is the low-level protocol that the Web Component abstracts.

**Best for:**

* Existing implementations already using postMessage
* Teams with specific iframe management requirements
* Legacy applications where adding new dependencies is difficult

**Architecture highlights:**

* Full control over iframe lifecycle and positioning
* Direct access to postMessage protocol
* Works cross-origin (different domains)
* Requires manual event parsing and error handling

<Card title="PostMessage Integration Guide" icon="messages" horizontal href="/assistant/postmessage-api">
  Learn how to integrate using the PostMessage API
</Card>

***

### Window API

<Frame>
  ```mermaid theme={null}
  graph TB
    subgraph "Your Application (same origin)"
        A[Parent Window]
        B[Direct Window Reference]
    end
    
    subgraph "Corti Assistant (same origin)"
        D[Assistant Interface]
        E[window.CortiEmbedded]
        F[Corti Platform APIs]
    end
    
    A -->|window.open or iframe| B
    B -->|Direct API Access| E
    E <--> D
    D <--> F
    
    style B fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px
    style E fill:#e8f4f8,stroke:#0066cc,stroke-width:2px
  ```
</Frame>

Same-origin integration where your application and Corti Assistant run on the same domain, allowing direct JavaScript API access through the global `window.CortiEmbedded` object.

**Best for:**

* Same-origin scenarios (both apps on same domain)
* Direct URL embedding in webviews or popup windows
* Mobile webview integrations where same-origin is guaranteed
* Scenarios requiring the simplest possible integration

**Architecture highlights:**

* No iframe or postMessage complexity
* Direct function calls to JavaScript API
* Only works when same-origin policy is satisfied
* Promise-based API with full TypeScript support

<Card title="Window API Integration Guide" icon="window-maximize" horizontal href="/assistant/window-api">
  Learn how to integrate using the Window API
</Card>

***

## Common integration flow

Regardless of which method you choose, the integration follows the same high-level flow:

<Steps>
  <Step title="Embed the Assistant">
    Add the Corti Assistant interface to your application using your chosen integration method (Web Component, iframe, or window reference).
  </Step>

  <Step title="Authenticate users">
    Implement OAuth2 authentication to obtain user tokens. All methods require user-based authentication with OAuth2 tokens (access, refresh, and ID tokens).

    <Card title="Authentication Guide" icon="key" horizontal href="/assistant/authentication">
      Learn how to set up OAuth2 authentication for your users
    </Card>
  </Step>

  <Step title="Initialize the Assistant">
    Pass authentication tokens to the Assistant and configure the interface (features, appearance, locale).
  </Step>

  <Step title="Create clinical interactions">
    Use the API to create interactions that represent clinical encounters, associate them with patient data, and manage their lifecycle.
  </Step>

  <Step title="Handle events">
    Listen for events from the Assistant (document generated, recording started, errors, etc.) and update your application UI accordingly.
  </Step>
</Steps>

***

## Authentication requirements

All three integration methods require OAuth2 user authentication. See the [Authentication Guide](/assistant/authentication) for complete setup instructions.

<Info>
  All Embedded Assistant integrations require user-based OAuth2 authentication with `access_token`, `refresh_token`, and `id_token`. Client credentials and machine-to-machine flows are not supported.
</Info>

***

## API capabilities

Once embedded and authenticated, all three integration methods provide access to the same comprehensive API:

<AccordionGroup>
  <Accordion title="Session management" icon="user">
    * Authenticate users with OAuth2 tokens
    * Refresh authentication tokens
    * Configure interface features and appearance
    * Set language and locale preferences
  </Accordion>

  <Accordion title="Clinical interactions" icon="heart-pulse">
    * Create new clinical interactions - Associate encounters with patient context
    * Manage interaction lifecycle - Navigate between sessions
  </Accordion>

  <Accordion title="Audio and recording" icon="mic">
    * Start and stop audio recording - Control recording state - Monitor recording status - Handle recording events
  </Accordion>

  <Accordion title="Document generation" icon="file-text">
    * Add clinical facts to interactions - Generate documents from captured data - Retrieve available templates - Configure document generation behavior
  </Accordion>

  <Accordion title="Event monitoring" icon="bell">
    * Listen for interaction events
    * Monitor document generation status
    * Track recording state changes
    * Handle errors and warnings
  </Accordion>
</AccordionGroup>

<Card title="Complete API Reference" icon="book" horizontal href="/assistant/api-reference">
  Full documentation of all API methods, parameters, and return types
</Card>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Choose Web Component" icon="puzzle-piece" href="/assistant/web-component-api">
    Modern, recommended approach with framework support
  </Card>

  <Card title="Choose PostMessage" icon="messages" href="/assistant/postmessage-api">
    Direct iframe control with manual postMessage handling
  </Card>

  <Card title="Choose Window API" icon="window-maximize" href="/assistant/window-api">
    Same-origin integration with direct API access
  </Card>

  <Card title="View Working Examples" icon="code" href="https://github.com/corticph/corti-examples/tree/main/embedded-assistant">
    Complete TypeScript and React examples on GitHub
  </Card>
</CardGroup>