Set up Web SDK channel

Back to SDK 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.

Choose your authentication mode before you begin. It determines which settings and installation steps apply.

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.

Open SDK Keys

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

Platform administration keys that begin with abl_ can’t bootstrap the Web SDK. Use an SDK key.

Create a website-specific SDK key

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

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.

An empty allowlist accepts every origin and isn’t recommended.

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.

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.

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.

If you select Hosted token exchange, complete the next step. Otherwise, skip to Select the Public SDK Key and Create the Channel.

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.

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:

Review authentication

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

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.

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 select Add themes to tune the widget to match your host site. Choose the launcher position, select or create a theme, and preview colors, typography, message bubbles, timestamps, and compose-bar behavior against your site.

Save the configuration

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

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.

Script tag
npm package

Copy the embed code.
Replace YOUR_PUBLIC_API_KEY with the full pk_ value of the Public SDK Key bound to this channel.
Paste the code before the closing </body> tag.
The widget appears on your site automatically.

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.

Install the package with your package manager (npm, pnpm, or yarn).
npm install @koreai/artemis-web-sdk
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.
Store the public key in an environment variable and never commit it to source control.

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.

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.

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 two tabs, Configuration 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. A sidebar on the right is visible on both tabs.

Section	Description
Environment	The environment the channel follows (for example, `Development`) and its Active Deployment. Select Modify to change which environment handles incoming messages.
Channel details	Channel (Web SDK), Connection Type (`SDK Channel`), Identifier (the unique channel ID, a UUID), Created, and Updated.

The Configuration tab contains the settings described in 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 Testing tab contains the preview link and installation code described in 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.

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prepare the Public SDK Key

Create a Web SDK channel

Configure the channel

Install the widget

Manage an existing channel

Troubleshooting

​Prepare the Public SDK Key

​Create a Web SDK channel

​Configure the channel

​Install the widget

​Manage an existing channel

​Troubleshooting

Prepare the Public SDK Key

Create a Web SDK channel

Configure the channel

Install the widget

Manage an existing channel

Troubleshooting