Headless SDK¶

Use the Headless SDK when you want to build your own Traveln UI but still use Traveln tenant routing, SSO, redirects, iframe embeds, and destination flows.

Unlike the iframe widgets, the SDK does not render a Traveln prompt box or button. Your page owns the UI, then calls Traveln.start(...) when the user chooses an action.

Best for¶

• Custom partner home pages
• Existing account dashboards
• Native-looking tenant nav bars and cards
• Flows where your app collects dates, destinations, or filters before launching Traveln
• Partner-owned iframe shells that should keep users in your product layout
• Specific-chat embeds where your app already knows the private chat UUID

Quick start¶

<script src="https://cdn.traveln.ai/sdk/v1/traveln-sdk.js"></script>
<script>
  Traveln.init({
    tenant: "your-tenant-slug",
    tokenUrl: "/api/traveln/sso/",
    ssoLoginUrl: "/sso-login/",
    locale: "en"
  });

  function openPlanner() {
    Traveln.start({
      target: Traveln.TARGETS.PLANNER,
      prompt: "Plan a family trip to Cairo"
    });
  }
</script>

Initialization¶

Call Traveln.init(...) once after loading the script.

Launch targets¶

External redirect¶

External redirect is the default SDK flow. Your UI calls a method, the SDK gets a token from your backend, then the browser navigates through /sso-login/ to the requested Traveln destination.

Traveln.start({
  target: Traveln.TARGETS.BOOKINGS
});

Use external redirect when Traveln should take over the browser tab after the partner action.

SDK iframe embed¶

Use an iframe shell when the partner page should keep its navigation, layout, or surrounding context. The SDK can build the authenticated SSO URL, including embed parameters, and your app can mount it in an iframe that you own.

const result = await Traveln.getSSOToken({});

const src = Traveln.buildRedirectUrl({
  token: result.token,
  traceId: result.traceId,
  target: Traveln.TARGETS.BOOKINGS,
  embed: {
    channel: "partner-bookings-frame",
    parentOrigin: window.location.origin
  }
});

document.querySelector("#traveln-frame").src = src;

For planner iframes, pass either a prompt or a chatId. For trips, bookings, and accommodation search, a chat UUID is not required.

const result = await Traveln.getSSOToken({
  prompt: "Plan a family trip to Cairo"
});

const src = Traveln.buildRedirectUrl({
  token: result.token,
  traceId: result.traceId,
  target: Traveln.TARGETS.PLANNER,
  prompt: "Plan a family trip to Cairo",
  embed: {
    channel: "partner-planner-frame",
    parentOrigin: window.location.origin
  }
});

Iframe embedding requires the parent origin to be approved for the tenant. Traveln validates the parent origin before rendering embed-safe planner responses.

SDK OpenChat embed¶

Use Traveln.openChat(...) when the partner application already has a private Traveln chat UUID and wants the SDK to create the iframe.

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

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);
  }
});

chatId must be a valid UUID. The SDK passes chat_id to your token endpoint and then loads /sso-login/ with target=planner, chat_id, tn_embed=1, tn_channel, and tn_parent_origin.

OpenChat does not delegate private chat access to the browser. Traveln still enforces chat ownership on the backend when the iframe loads the chat.

Accommodation filters¶

Accommodation filters are optional. Invalid values are ignored.

Traveln.startAccommodationSearch({
  filters: {
    countryId: "00000000-0000-0000-0000-000000000000",
    cityId: "00000000-0000-0000-0000-000000000000",
    checkIn: "2026-07-01",
    checkOut: "2026-07-05",
    adults: 2,
    children: 0,
    minPrice: 100,
    maxPrice: 500
  }
});

Filter values are forwarded to Traveln as af_* query parameters during SSO and applied by the accommodation search flow.

Token-only flow¶

Use getSSOToken if your app needs to inspect or defer the redirect:

const result = await Traveln.getSSOToken({
  prompt: "Plan a wellness trip"
});

const url = Traveln.buildRedirectUrl({
  token: result.token,
  traceId: result.traceId,
  target: Traveln.TARGETS.PLANNER,
  prompt: "Plan a wellness trip"
});

window.location.href = url;

Runtime flow¶

1. Your UI calls a Traveln SDK method.
2. The SDK requests a signed token from your backend tokenUrl.
3. Your backend validates the current user and returns { "token": "..." }.
4. The SDK loads tenant config from /widget/v1/<tenant>/config.json.
5. The SDK redirects or iframe-loads ssoLoginUrl with the token, target, trace ID, prompt, optional filters, optional chat_id, and optional embed metadata.
6. Traveln verifies SSO, creates the tenant session, and opens the requested destination.

Anonymous or guest mode¶

If your user is not known yet, your backend can still return a valid SSO token with is_anonymous: true. Traveln creates a guest session. Tenant UI can use this to show a partner-specific Login CTA while still allowing limited guest access.

Related docs¶

• Client integration
• Server-side token generation
• SDK OpenChat Embed
• Customization