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

# Set up Web SDK channel

[Back to SDK](https://koreai.mintlify.site/agent-platform/channels.md#sdk-channels)

Embed a chat widget in your website with a single script tag. Web SDK is a deployment channel that connects a chat and voice widget on your site to a specific agent deployment.

The Web SDK channel supports two authentication modes:

* **Anonymous / Public-key bootstrap**: for client-only apps. The browser bootstraps Runtime directly with a publishable `pk_*` key. The key identifies the website and channel, not the end user.
* **Hosted token exchange**: for setups where your backend can hold a server secret and authenticate the user. Your backend issues one-time bootstrap tokens, and the browser never holds a long-lived credential.

> [!NOTE]
>
> Choose your authentication mode before you begin. It determines which settings and installation steps apply.

> [!TIP]
>
> Studio also provides in-product guidance. On the **Web SDK** channel page, click **Setup instructions** to open a step-by-step panel that covers key preparation, channel creation, widget configuration, installation, verification, and security.

## Prepare the Public SDK Key

Both authentication modes use a Public SDK Key (`pk_*`) that supplies the channel's SDK permissions. Create one before you create the channel.

**1. Open SDK Keys**

Go to **Deployments** > **API Keys** and stay on the **SDK Keys** tab.

> [!NOTE]
>
> Platform administration keys that begin with `abl_` can't bootstrap the Web SDK. Use an SDK key.

**2. Create a website-specific SDK key**

Use a clear name such as `Support Website Production`. Create separate keys for development, staging, and production.

**3. Restrict the key's Allowed Origins**

Add each website origin with its scheme and host, without a path, for example `https://support.example.com`. Add `localhost` only to a development key.

> [!WARNING]
>
> An empty allowlist accepts every origin and isn't recommended.

**4. Copy the pk\_ value**

Copy the full Public SDK Key when Studio reveals it. Studio doesn't show the full value again. When you create the channel, you select the saved key by name and prefix.

## Create a Web SDK channel

To create a Web SDK channel, go to **Deployments** > **Channels** > **SDK** > **Web SDK** > **New connection** and complete the following steps in order.

**1. Set Up the Connection**

On the **New Web SDK Connection** page, provide the following fields.

| Field | Description |
| :- | :- |
| **Display Name** | A label for the connection (up to 255 characters). Use a name that identifies the site and environment, for example `Support Widget Production`. |
| **Environment** | Where the agent runs. Select a published environment to follow its active deployment automatically, or leave the default to use the working copy during development. |
| **Authentication** | How customer browsers bootstrap SDK sessions. Select **Anonymous / Public-key bootstrap** or **Hosted token exchange**. |

**2. Choose an Authentication Mode**

| Mode | When to use |
| :- | :- |
| **Anonymous / Public-key bootstrap** | Browser or client app for low-assurance public experiences. Store the public `pk_*` key, runtime endpoint, and channel selection in client-side configuration. No ABL secret is required, and customer servers don't need to sign or exchange credentials. This mode authenticates app bootstrap, not the end user. |
| **Hosted token exchange** | Customer backend that must authenticate the user and pass verified identity or secure attributes to Runtime. The backend stores a reveal-once `sk_*` server secret and issues one-time `bootstrapToken` values. The browser stores only the short-lived token, runtime endpoint, and project ID. |

> [!NOTE]
>
> If you select **Hosted token exchange**, complete the next step. Otherwise, skip to Select the Public SDK Key and Create the Channel.

**3. Set the Token Envelope Policy (Hosted Token Exchange Only)**

The **Token envelope policy** controls whether Hosted Exchange SDK bootstrap and session credentials are signed or encrypted.

| Option | Meaning |
| :- | :- |
| Use runtime default | Defers to the project-level default Hosted Exchange token envelope policy. |
| Signed tokens | Issues signed bootstrap and session tokens only. Use for explicit compatibility or rollback. |
| Prefer encrypted tokens (`jwe_preferred`) | Uses encrypted (JWE) tokens when Runtime's encryption capability is ready, and falls back to signed tokens otherwise. This is the recommended rollout. |
| Require encrypted tokens (`jwe_required`) | Requires encrypted issuance and verification end to end, and fails closed rather than returning a signed token. Use only after Studio confirms Runtime can issue and verify JWE bootstrap and session tokens. |

**4. Select the Public SDK Key and Create the Channel**

Select the active **Public SDK Key** that you prepared for this website and environment, then select **Create**. The selected key supplies the channel's effective SDK permissions in both authentication modes.

Creating the channel binds it to the key. To finish setup, open the connection and configure Allowed Origins, widget mode, features, position, and theme before you copy the installation code.

## Configure the channel

Once the channel is created, select it, then go to the Configuration tab to update:

**1. Review authentication**

Under **Web SDK Settings** > **Authentication**, use the **Auth mode** toggle to choose **Anonymous / Public-key bootstrap** or **Hosted token exchange**.

**2. Set the Allowed Origins and other settings**

| Field | Description |
| :- | :- |
| **Allowed Origins (CORS)** *(optional, both modes)* | One URL per line, for example, `https://example.com`, `https://*.example.com`. These origins are enforced for the public key linked to this SDK channel. |
| **Server secret** *(Hosted token exchange only)* | Studio generates the `sk_*` server secret automatically on creation and reveals it once. Copy it and store it in your customer backend immediately, because it can't be viewed again. Your backend sends it in the `X-SDK-Channel-Secret` header when it requests customer sessions. **Server Secret Status**, **Server Secret Prefix**, and **Last Rotated** are shown afterward. Use **Rotate server secret** to issue a new secret. The previous secret stops working immediately. |
| **Customer-issued encrypted bootstrap** *(Hosted token exchange only, toggle, off by default)* | Accept customer-backend-issued JWE bootstrap tokens so sensitive and identity data can be encrypted before it reaches Runtime. |

**3. Configure widget behavior**

The same widget behavior settings apply in both authentication modes.

| Field | Description |
| :- | :- |
| **Widget Mode** | **Chat Only**, **Voice Only**, or **Chat + Voice**. Enable only the capabilities your site needs. Voice requires browser media support and a configured Runtime voice pipeline or realtime voice model. |
| **Features** | Toggle **Chat** and **Voice** independently. |
| **Show Agent Activity Updates** | Displays transient handoff, delegation, and reasoning activity for this SDK channel. It uses the Project Settings runtime Activity Updates policy for configured categories, privacy, and tool previews. Leave it off for customer-facing widgets unless users should see internal status text. |
| **Theme** | Choose a preset or tune the Web SDK widget to match your host site. Select **New Theme** or **Add themes**, choose the launcher position, select or create a theme, and preview colors, typography, message bubbles, timestamps, and compose-bar behavior against your site. |
| **Voice Pipeline** | Appears when **Widget Mode** is **Voice Only** or **Chat + Voice**. Select how the widget handles voice conversations. See the options below. |

**Voice Pipeline**

| Option | Description |
| :- | :- |
| **Standard STT/LLM/TTS** | Handles voice through separate stages: Deepgram for speech recognition, an LLM, and ElevenLabs for speech synthesis. |
| **Realtime Voice Model** | Uses direct model-to-model audio. When you select this option, set the realtime settings described below. |
| **Auto** | Uses the agent hint to decide which voice pipeline handles the conversation. |

**Realtime Voice Model settings**

When you select **Realtime Voice Model**, set the following fields.

| Field | Description |
| :- | :- |
| **Realtime orchestration** | Controls how Runtime takes part in realtime voice turns. Default: **Legacy — model-selected tools**. - **Legacy — model-selected tools**: Preserves existing behavior. - **Runtime guarded**: Keeps model flexibility but blocks out-of-order FLOW tools. - **Runtime owned**: Routes every finalized utterance through the canonical runtime turn. |
| **Semantic convergence** | Controls whether realtime voice turns use the coordinated utterance runtime. For example, **Enforce**. |
| **Response wording owner** | Controls who owns the wording of spoken responses. - **Runtime text** (recommended): Runtime provides the wording. - **Provider-grounded voice**: Opt-in and available with Gemini Live only. It falls back to Runtime text for unsafe or unsupported turns. |

**4. Save the configuration**

Click **Save Configuration**. Save before you generate installation code, because preview links and installation snippets use the saved channel configuration.

## Install the widget

Open the **Testing** tab for the channel. It provides the secure preview link and the installation code for the saved configuration.

**Generate a secure preview**

Under **Secure Preview Link**, select **Generate new link** to create a secure, time-limited link to preview your widget. The link expires after 7 days. Use the preview to confirm the saved theme, launcher position, chat behavior, and any enabled voice controls before you install the widget on your site.

Under **Add to your site**, choose **Script tag** or **npm package**. Use the script tag for a simple HTML integration. Use the npm package for framework lifecycle control and typed configuration.

> [tab] Script tag
>
> 1. Copy the embed code.
>
> 2. Replace `YOUR_PUBLIC_API_KEY` with the full `pk_` value of the Public SDK Key bound to this channel.
>
> 3. Paste the code before the closing `</body>` tag.
>
> 4. The widget appears on your site automatically.
>
> > [!NOTE]
> >
> > The embed code is generated per channel and already includes the correct `project-id`, `endpoint`, and `channel-id` for this connection. Only the API key placeholder needs to be replaced. If your site uses a Content Security Policy, make sure it allows the generated script and the Runtime endpoints.

> [tab] npm package
>
> 1. Install the package with your package manager (**npm**, **pnpm**, or **yarn**).
>
>    ```bash theme={null}
>    npm install @koreai/artemis-web-sdk
>    ```
>
> 2. Import `AgentWidget` in your app entry file and call `AgentWidget.init()` once with your project ID, Runtime endpoint, channel ID, and Public SDK Key. The **Testing** tab generates a complete sample that also includes the saved mode, position, feature flags, and theme options.
>
> 3. Store the public key in an environment variable and never commit it to source control.
>
> > [!NOTE]
> >
> > Using React, Vue, or Angular? Call `AgentWidget.init()` once on mount and `AgentWidget.destroy()` on unmount. Framework wrappers are on the roadmap.

Test the page from an origin that's allowed on both the channel and the key. Opening a local HTML file uses a `null` origin and is rejected. Use an HTTP development server instead.

> [!NOTE]
>
> The `pk_` key is browser-visible by design. It isn't a platform administration secret, but production safety depends on narrow origin rules, channel permissions, and environment isolation.

**Hosted token exchange installation**

In Hosted token exchange mode, your backend authenticates the user, calls `POST /api/v1/sdk/customer-sessions` with the `X-SDK-Channel-Secret` header, and returns only the single-use `bootstrapToken` (valid for 300 seconds) to the browser. In the browser, install the npm package and supply `bootstrapTokenProvider`, so that the SDK fetches a fresh token from your backend whenever it initializes or reconnects. Use this approach instead of the generated API-key snippet.

* Don't send permissions from the backend. Runtime derives them from the bound Public SDK Key.
* Don't include public-only fields such as `apiKey`, `channelId`, or `clientSessionIdentifier` in a Hosted configuration. Verified identity and secure attributes come from the backend-issued token.
  For the step-by-step flow, click **Setup instructions** on the Web SDK channel page.

> [!WARNING]
>
> Don't bake a one-time token into static HTML. Although the custom element accepts a bootstrap-token attribute, a static token expires and can't survive reconnects. Set the `bootstrapTokenProvider` JavaScript property before you connect or append the widget.

**Verify and secure the installation**

Before you go live, test a new and a continued conversation (and voice, if enabled) from the secure preview and from your production origin. Voice requires HTTPS or localhost and microphone access.

Follow these security practices:

* Restrict origins on both the Public SDK Key and the channel, and use separate keys and channels for development, staging, and production.
* Keep the `sk_` server secret on your backend only, and rotate it immediately if it's exposed.
* Treat SDK tokens, bootstrap tokens, and WebSocket tickets as credentials. Keep them out of URLs, logs, analytics, and browser storage.

## Manage an existing channel

Open a channel from **Deployments** > **Channels** > **SDK** > **Web SDK**. The channel page has three tabs: **Configuration**, **Deployment**, and **Testing**.

The channel header shows the channel name, its environment, its status (for example, *Active*), and when it was last updated. Use the **…** menu for additional channel actions.

The **Configuration** tab contains the settings described in [Configure the channel](#configure-the-channel). Changing the auth mode, token envelope policy, allowed origins, or widget settings updates the live channel after you click **Save Configuration**.

The **Deployment** tab binds the channel to an environment.

| Section | Description |
| :- | :- |
| **Environment Binding** > **Environment** | Selects which deployed version handles incoming messages, for example, `Development`. |
| **Active Deployment** | Shows the deployment bound to the selected environment and when it was deployed. |

Select **Save Changes** after you switch the environment.

The **Testing** tab contains the preview link and installation code described in [Install the widget](#install-the-widget).

## Troubleshooting

* **`Origin not allowed`:** add the page's exact origin to both the Public SDK Key and the channel **Allowed Origins**, and serve the page over HTTP or HTTPS (not a local file).
* **Widget doesn't appear:** confirm the full snippet is before the closing `</body>` tag, your Content Security Policy allows the script, and at least one capability is enabled.
* **Saved changes are missing:** save the Configuration, then reload **Testing** to regenerate the snippet.
* **Hosted exchange errors** (`INVALID_BOOTSTRAP_REQUEST`, `SDK_JWE_UNAVAILABLE`): mint a fresh token for each initialization, and check the token envelope policy.
  For the full troubleshooting checklist, click **Setup instructions** on the Web SDK channel page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.