Links & navigation

When a shopper taps a product card in the conversation, the assistant should get out of the way and your product screen should open. In mode=sdk the runtime never navigates on its own — it hands you the URL and waits.

// web → host
{ "name": "openExternalUrl",
  "payload": {
    "url": "https://shop.example.com/p/1010600-88244?utm_source=loopsai&utm_medium=chat&utm_campaign=product_recommendation&utm_content=carousel&utm_term=1010600-88244",
    "target": "_blank"
  } }

Every outbound link comes through this one action — product cards, links the assistant writes in a message, the privacy policy. The URL arrives verbatim, with its full query string.

Pick a destination

Three valid answers. You can mix them — decide per URL.

Close, then navigate

For a product link the expected behaviour is: dismiss the assistant, then push the product screen. Do it in that order so the user does not see your screen appear behind a chat sheet.

function onOpenExternalUrl(url) {
  // Opt in per URL shape; everything else keeps its web context.
  const route = nativeRouteOptIn(url); // null → in-app browser

  if (route) {
    send("closeOverlays");   // close any in-chat overlay first
    dismissChatContainer();  // your sheet / route pop
    navigate(route);
    return;
  }

  openInAppBrowser(url); // default — keeps the chat open behind it
}

Map the URL to a native route

Match on the path, and carry the identifiers through. Your product URLs already contain everything you need.

const SHOP_HOSTS = new Set(["shop.example.com", "www.example.com"]);

function toNativeRoute(raw) {
  let url;
  try {
    url = new URL(raw);
  } catch {
    return null;
  }
  if (!SHOP_HOSTS.has(url.hostname)) return null;

  const productMatch = url.pathname.match(/^\/p\/([^/]+)/);
  if (productMatch) {
    return { name: "Product", params: { code: productMatch[1] } };
  }

  const categoryMatch = url.pathname.match(/^\/c\/([^/]+)/);
  if (categoryMatch) {
    return { name: "Category", params: { slug: categoryMatch[1] } };
  }

  return null; // unknown shape → in-app browser
}

private let shopHosts: Set<String> = ["shop.example.com", "www.example.com"]

func nativeRoute(for url: URL) -> Route? {
    guard let host = url.host, shopHosts.contains(host) else { return nil }
    let parts = url.pathComponents.filter { $0 != "/" }

    if parts.first == "p", parts.count > 1 { return .product(code: parts[1]) }
    if parts.first == "c", parts.count > 1 { return .category(slug: parts[1]) }
    return nil
}

private val shopHosts = setOf("shop.example.com", "www.example.com")

fun nativeRoute(raw: String): Route? {
    val url = raw.toUri()
    if (url.host !in shopHosts) return null
    val parts = url.pathSegments

    return when {
        parts.size > 1 && parts[0] == "p" -> Route.Product(parts[1])
        parts.size > 1 && parts[0] == "c" -> Route.Category(parts[1])
        else -> null
    }
}

Always fall back to the in-app browser for a URL you do not recognise. New link types will appear as your catalog and content grow, and a dead tap is worse than a web page.

Attribution

Product URLs carry the parameters your Loops AI configuration is set up to add:

They may also carry loopsai_open=sidebar, which is meant for your web storefront — it opens the web widget on the landing page. Harmless; ignore it in a native route.

The runtime appends them before it hands you the URL, and every transport passes the query string through untouched — so attribution survives as long as the URL ends up in a web context. An in-app browser is a web context; a native screen is not.

Keep navigation out of the chat WebView

Product links open as target: "_blank". Belt and braces: even with openExternalUrl handled, make sure the WebView itself can never navigate away from the chat host — a WebView showing your storefront with your JavaScript bridge attached is both a broken experience and a security problem.

Same-host navigation inside chat.loopsai.com must stay allowed — that is the runtime doing its job.

Closing the chat

Three things can close it. Handle all three.

case "closeChat":
  dismissChatContainer();
  break;

Prefer hiding your container over destroying the WebView. The conversation, scroll position and connection survive, so reopening is instant instead of a fresh load.

Returning from the standalone size guide

The standalone size route can hand the user back to the conversation:

{ "name": "startSizeGuideInline",
  "payload": { "product": { "productCode": "1010600-88244", "gender": "women" } } }

Close the size sheet, open the chat, and replay it as a startSizeGuide:

case "startSizeGuideInline":
  dismissSizeSheet();
  presentChat();                       // wait for `ready`
  onReady(() => {
    send("initContext", {});
    send("startSizeGuide", { productContext: payload.product });
  });
  break;

Deep links into the assistant

The reverse direction is just a URL. Anything that can open a screen in your app — a push notification, a marketing link, a shortcut — can open the assistant in a specific state, because every entry point has a URL parameter:

Full list: The chat URL.

Next: Checklist & troubleshooting.