SDK OpenChat Embed¶

SDK OpenChat Embed lets a partner page mount an authenticated Traveln chatbot iframe for one specific private chat UUID.

Use this when your application already knows the Traveln chat UUID and wants to reopen that conversation inside a partner-owned page.

Requirements¶

Headless SDK loaded from the Traveln CDN.
Traveln.init(...) called with the tenant slug, token endpoint, and SSO login URL.
A valid private chat UUID owned by the authenticated Traveln user.
A DOM container where the SDK can mount the iframe.
The parent origin approved for the tenant's embed policy.

Basic usage¶

<script src="https://cdn.traveln.ai/sdk/v1/traveln-sdk.js"></script>

<div id="traveln-chat"></div>

<script>
  Traveln.init({
    tenant: "your-tenant-slug",
    tokenUrl: "/api/traveln/sso/",
    ssoLoginUrl: "/sso-login/",
    locale: "en"
  });

  Traveln.openChat({
    chatId: "11111111-1111-1111-1111-111111111111",
    container: "#traveln-chat",
    iframeAttrs: {
      class: "traveln-chat-frame"
    },
    onReady: (event) => {
      console.log("Traveln chat ready", event);
    },
    onError: (event) => {
      console.error("Traveln chat error", event);
    }
  });
</script>

Public API¶

Traveln.openChat({
  chatId,
  container,
  iframeAttrs,
  onReady,
  onError
});

Option	Required	Description
`chatId`	Yes	Private Traveln chat UUID.
`container`	Yes	CSS selector or DOM element where the SDK mounts the iframe.
`iframeAttrs`	No	Extra iframe attributes. `src` is ignored for safety.
`onReady`	No	Called when the iframe posts `traveln.chat.ready`.
`onError`	No	Called when validation, SSO, or iframe bootstrapping fails.

Token endpoint payload¶

OpenChat sends chat_id to the partner token endpoint:

{
  "trace_id": "string",
  "chat_id": "11111111-1111-1111-1111-111111111111"
}

The token endpoint should keep using the normal SSO token contract. It may include the current user identity and host binding in the signed payload. The private chat permission check remains enforced by Traveln when the chatbot iframe loads the chat.

SSO URL behavior¶

After receiving a token, the SDK iframe-loads the SSO URL with:

Parameter	Purpose
`token`	Signed tenant SSO token.
`target=planner`	Opens the trip planner chatbot.
`chat_id`	Initial private chat UUID.
`tn_embed=1`	Requests embed-safe rendering.
`tn_channel`	Opaque SDK channel for iframe events.
`tn_parent_origin`	Parent page origin for frame-policy validation.

Iframe events¶

The iframe may post these events to the parent window:

Event	Meaning
`traveln.chat.ready`	Chat iframe finished bootstrapping.
`traveln.chat.error`	The iframe or SSO flow failed.
`traveln.chat.height`	Optional height update for iframe resizing.

The SDK filters events by channel before calling callbacks.

Error handling¶

Handle validation and runtime failures in onError:

Traveln.openChat({
  chatId,
  container: "#traveln-chat",
  onError: ({ message }) => {
    showInlineError(message || "Unable to open Traveln chat");
  }
});

Common failures:

Missing or invalid UUID.
Missing container.
Token endpoint returns a non-2xx response or omits token.
Parent origin is not approved for the tenant.
Authenticated user does not own the requested private chat.