V3 Deep Links — Lilith Metaverse

This file is the deployment contract for V3 links emitted by V1 messaging channels and handled by the V1 mobile companion.

Outbound Telegram, WhatsApp, push, email, and SMS messages must use the canonical HTTPS form so links survive app-install state, link previews, forwarding, and desktop-to-mobile handoff. The custom scheme is the installed app target that the mobile client maps to after the OS resolves the universal link or app link.

Host and scheme:

Canonical HTTPS origin: https://app.oshun.com
Custom scheme authority: oshun://v3
Universal/app-link path family: /v3 and /v3/*
Outbound source attribution: append ?source=<channel> where channel is one of telegram, whatsapp, push, email, or sms.

Route Templates#

Surface	Canonical HTTPS URL	Custom-Scheme URL	Required Parameters
V3 companion home	`https://app.oshun.com/v3`	`oshun://v3`	none
Tara bookings	`https://app.oshun.com/v3/tara/bookings`	`oshun://v3/tara/bookings`	none
Tara booking detail	`https://app.oshun.com/v3/tara/bookings/{bookingId}`	`oshun://v3/tara/bookings/{bookingId}`	`bookingId`
Arete continuations	`https://app.oshun.com/v3/arete/continuation`	`oshun://v3/arete/continuation`	none
Arete continuation detail	`https://app.oshun.com/v3/arete/continuation/{continuationId}`	`oshun://v3/arete/continuation/{continuationId}`	`continuationId`
Ticket inventory	`https://app.oshun.com/v3/tickets`	`oshun://v3/tickets`	none
Ticket detail	`https://app.oshun.com/v3/tickets/{ticketId}`	`oshun://v3/tickets/{ticketId}`	`ticketId`
Follow list	`https://app.oshun.com/v3/follows`	`oshun://v3/follows`	none
Follow detail	`https://app.oshun.com/v3/follows/{followId}`	`oshun://v3/follows/{followId}`	`followId`
Saraswati signed-edition wallet	`https://app.oshun.com/v3/saraswati/wallet`	`oshun://v3/saraswati/wallet`	none
Saraswati signed-edition detail	`https://app.oshun.com/v3/saraswati/wallet/{editionId}`	`oshun://v3/saraswati/wallet/{editionId}`	`editionId`

Channel Helpers#

Use @oshun/messaging-channels for outbound V3 links:

import { buildV3MessagingSharePayload } from '@oshun/messaging-channels';

const share = buildV3MessagingSharePayload({
  channel: 'telegram',
  link: {
    surface: 'tara-booking',
    bookingId: 'booking-tara-sunrise-2026-05-20',
  },
});

The share.url value is the URL to send in the channel body or button:

text

https://app.oshun.com/v3/tara/bookings/booking-tara-sunrise-2026-05-20?source=telegram

The payload also carries canonicalHttpsUrl without source attribution and customSchemeUrl for native QA, app-store review scripts, and mobile route contract tests. Do not send oshun://... links directly through Telegram, WhatsApp, push, email, or SMS.

Launch Behavior#

A user taps the canonical HTTPS URL.
iOS Universal Links or Android App Links open the V1 mobile companion when installed and verified for app.oshun.com.
The V1 mobile companion resolves the /v3/* path into the matching V3 surface and asks the authenticated launch router for the UE5 Lilith target.
If the UE5 native client is installed, the companion opens the native launch deep link.
If the UE5 native client is not installed, the companion opens the original canonical HTTPS route in the V1 web fallback with the bearer session carried only in the URL fragment.