Skip to main content

Embedding Corti Assistant: Typical Workflow

Updated over a week ago

✅ Overview

This guide walks you through embedding Corti Assistant in a web app using an iframe. You'll authenticate with OAuth2, create an interaction via the API, load the iframe, and then fetch the resulting documentation.

While it's focused on web, the overall workflow is applicable to most embedded workflows.

For a higher-level introduction into embedding Corti Assistant, read the guide Embedding Corti Assistant via iFrame or Webview


1. 🔐 Authenticate Using OAuth2

PKCE is best practice for frontend apps, but other flows (e.g., Auth Code, ROPC, Client Credentials) are available depending on your use case. The link above provides guidance on choosing the right flow.


2. 🗂️ Create an Interaction

To begin a new session, you must create an interaction. This is done by making a POST request to the /interactions/ endpoint. You’ll typically include some metadata—such as a patient ID, user ID, or custom tags—that helps identify or categorize the session.

In return, you receive an interaction.id, which is your session handle. You'll need this ID in the next step to embed the Assistant.


3. 🧳 Embed the Corti Assistant iframe

Depending on your environment, the web app URL is one of:

  • https://assistant.us.corti.app

  • https://assistant.eu.corti.app

  1. Take the full auth response from Step 1 and Base64 encode it.

    await response.text();
    const b64_auth = btoa(data);

  2. Generate the web-app URL, passing in the interaction ID from Step 2 in the path and the base64 encoded JSON as a query parameter.

    const webAppUrl =
    `https://assistant.us.corti.app/session/${interactionId}?auth_response=${b64_auth}&embedded=true`

  3. Pass the web-app URL into the iframe. Ensure you set up the iframe exactly as below.

    <iframe
    name="iframe"
    id="frame"
    title="Corti Assistant"
    src="{{webapp_url}}"
    sandbox="allow-forms allow-modals allow-pointer-lock allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts allow-downloads"
    allow="microphone *; camera *; device-capture *"
    >
    </iframe>

4. 📄 Fetch the Documentation

Docs:

Once an interaction has taken place (e.g., a conversation is recorded and transcribed), you can retrieve the output documentation.

  • First, list all documents associated with an interaction by passing the interaction_id to the /documents/ endpoint.

  • Then, to access a specific document, pass its document_id to the /documents/{id} endpoint.

This allows you to display or further process the final output generated by Corti Assistant.


🧠 Developer Tips

  • Don’t store secrets in frontend JS.

  • Always validate HTTPS endpoints.

  • Use async/await to keep logic clean.

  • Refresh tokens if expired.

  • Use browser DevTools to debug iframe and auth flows.

Did this answer your question?