Skip to content

Headless SDK

Use the Headless SDK when you want to build your own Traveln UI but still use Traveln tenant routing, SSO, 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

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.

Option Required Description
tenant Yes Tenant slug assigned by Traveln.
tokenUrl No Your backend endpoint that returns { "token": "..." }. Default: /api/traveln/sso/.
ssoLoginUrl No Explicit SSO entrypoint. Default: /sso-login/. Use an absolute URL when launching across hosts.
locale No Locale used by tenant config and downstream Traveln screens. Default: en.
configBaseUrl No CDN config origin override. Usually omit this.
integrationMode No external_redirect, internal_iframe, or internal_embed_inline. Defaults to external_redirect; tenant config can override it.

Launch targets

Target Method Required data
Trip planner Traveln.startPlanner({ prompt }) or Traveln.start({ target: Traveln.TARGETS.PLANNER, prompt }) prompt
My Trips Traveln.openTrips() or Traveln.start({ target: Traveln.TARGETS.TRIPS }) none
Accommodation search Traveln.startAccommodationSearch({ filters }) or Traveln.start({ target: Traveln.TARGETS.ACCOMMODATION_SEARCH, filters }) optional filters

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 to ssoLoginUrl with the token, target, trace ID, prompt, and optional filters.
  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.