Legacy entry points and migration

This is the caller inventory for the native edition's owner-controlled switch, prepared on 16 October 2026. Source support is distinct from a production switch. js., ws., cdn., storage. and app.happytohelp.com remain on legacy. Alternate-brand and staging hosts remain where they are too. No DNS, TLS, AWS, mail routing, production application, plugin or payment configuration was changed. A new native installation does not become the recipient of old traffic merely because it contains imported records.

The decisions below cover C01, C02, C05, X03 and H16. “Native” means a caller can be migrated to the named native interface; “Drain” means retain the old receiver until its callers, active work and late deliveries have been explicitly accounted for. Neither label claims a live provider or real customer cutover was qualified.

Observed public callers

Only unauthenticated public GETs were used. No chat was opened, contact endpoint called, message sent or private account accessed. These are source observations, not browser execution or a complete inventory of every page/customer/session.

An initial default Python User-Agent received HTTP 403 from 12ui; the browser User-Agent returned its real titled page. No challenge interaction was attempted. Public project IDs above are installation identifiers, not secrets.

The Ramon static-source pass covered its directly referenced cookie-law-info, jQuery, Divi (scripts/fitvids/easypiechart/salvattore/common), advanced-ads, PixelYourSite (bind-first/cookie/SHA-256/public) and WordPress mediaelement scripts. These were read as text only; third-party widgets and tracking services were not fetched or executed.

Install

New native snippets use the native application origin and a project's public widget key. Save the customer's exact website origin in Widget settings first.

<script src="https://support.example.com/widget.js"
        data-api-origin="https://support.example.com"
        data-widget-key="PUBLIC_WIDGET_KEY" async></script>

For a retained legacy snippet, import the original project ID or retain its explicit public slug alias. The bridge resolves that ID/alias through GET /api/widget/legacy-project?projectId=… to the current native public widget key; the resolver checks the project's exact allowed origin, excludes deleted projects and returns no session. A new key does not require changing an old project-ID snippet when that source identity is retained.

When the native Worker serves /widget.js, it prefixes the script with the configured APP_ORIGIN as data-api-origin unless the script already supplies that attribute. Thus the old js. host can eventually serve this asset while its API remains on the native app origin. The option precedence is explicit apiOrigin, script data-api-origin, old apiUrl, then script URL origin. A separate asset host without the prefix needs explicit native-origin configuration or a coordinated rebuild; do not accidentally send native API calls to an unconfigured CDN. No host routing has been changed. See src/modules/legacy-import/README.md for the reviewed import contract.

The old standalone script contract accepts data-project, data-projectId, data-project-id, and data-config JSON (the old parser also permitted single quotes); queued h2h('init', {projectId}) and project_id occur in original instructions. Preserve #launch-chat on the customer's own host page. Never replace those emailed customer links with an invented support hostname.

JavaScript API

The original entry point exports h2h; the alternate HasContext build exports hasContext and uses hasContextQueue. Original source dispatches the following commands, independently of whether any public site currently calls them.

JavaScript options

Source options include projectId / project_id, targetElementId, open, selector, contact, settings, theme, text, conversationSettings, apiUrl, wsUrl and proxy. contact may contain name/email, identifier, identity hash and signed metadata. Old documentation locates consent at settings.await_consent; old code also inspected top-level await_consent. The native installation uses apiOrigin / widgetKey and a single native transport. Old apiUrl / wsUrl values must not cause a native widget to speak the legacy HTTP or encrypted WebSocket protocol. A proxy or raw collector caller needs an explicit migration decision; importing options alone does not qualify it.

Legacy-project mode deliberately strips hash, key, token, metadataHash and the entire old metadata object before native admission or updates. It warns when old credential/signature fields are present. Name/email and identifier remain unverified preferences. This includes the observed 12ui contact update: its old signature is not portable verified identity, and its metadata does not become verified native context. Old visitor sessions and transcript access remain on legacy; the bridge establishes fresh native visitor authority, not seamless old-session continuation.

To restore verified identified visitors and signed metadata, deliberately migrate the customer's trusted backend to this installation's current signatures and use the native widgetKey form. Native server validation then governs identity and metadata. Never publish secrets, accept unsigned metadata as verified, or convert old contact keys/JWTs into native sessions. settings, theme and text remain client preferences within server policy, not permission grants.

HTTP caller inventory

P below is /api/projects/{project} on https://app.happytohelp.com (or the explicitly configured old API origin). Every row is Drain for unchanged old clients. Similar native features do not establish response-shape compatibility.

routes/api.php declares resource families for theme-images, macros, contacts, conversations, buckets, completions, collector, participants and notes. The table lists implemented controller actions, not every boilerplate verb a resource router could generate. An undeclared external caller is an inventory item to resolve before retiring the family, not a reason to guess a translation. Native operator APIs are /api/dashboard/..., /api/management/... and scoped bearer /api/v1/...; native conversation transport is /api/conversations/....

WebSocket caller inventory

Keep wss://ws.happytohelp.com/ and the alternate wss://ws.hascontext.com/ on legacy for cached scripts and active clients. A hostname redirect cannot translate this protocol.

The old handshake supplies contact_id plus key or token, or agent_id plus project_id and token; optional conversation_id selects history. The widget subsequently sends auth with encrypted session/contact keys. Internal-mode flags/tokens are server infrastructure, never a public privilege.

Every old action below is Drain, including where native has an equivalent:

Native sockets are /api/conversations/{id}/socket and /api/projects/{id}/socket on the application origin, with native authentication, origin checks and replay cursors. Drain evidence must include cached versions, open connections, external operators/integrations, pending requests and late reconnects; zero current connections alone does not prove cached callers migrated.

Links, help hosts and retained files

Configure confirmed help hosts through deployment configuration, for example:

{
  "help.customer.example": "retained-project-slug",
  "old-help.example": "retained-project-id"
}

Set this JSON string as PUBLIC_HELP_HOSTS. Keys are exact lowercase hostnames, without scheme, path or wildcard; values are retained project IDs or explicit public aliases. The configured canonical APP_ORIGIN hostname keeps ordinary application/homepage routing even if listed. Only a confirmed mapped host's root, /search and single article-slug paths receive help-center dispatch, with relative links and published-project checks; reserved application/API paths keep their normal routing. No suffix match, forwarded host or arbitrary request host selects a tenant. DNS/TLS ownership remains the owner's final routing step.

For files, inventory the exact old URL, owning project, media/message/object ID, content hash, filename/type, original visibility and required current authority. Authorized imported bytes live behind native GET /api/conversations/{conversation}/media/{mediaId}. This route rechecks the actor's current project and contact/conversation authority; a copied URL cannot grant access. Retain existing storage access controls during the transition. Do not automatically redirect a public old URL to protected bytes, publish a private R2 bucket, embed a bearer token in a redirect, or weaken media access to make an emailed URL work. A private legacy URL needs an authenticated resolver or the retained protected legacy origin; only proven public static objects may have a reviewed public replacement. No such production resolver or object ACL change is claimed here.

Mailboxes, callbacks and other external receivers

Plugin SDK migration (X03)

Decision: explicitly migrate each plugin consumer or retain it on legacy. Generic native iframe support is not proof that arbitrary legacy SDK consumers work. ChargeDesk's external plugin URL is https://app.chargedesk.com/installed/happytohelp; it is separate from HappyToHelp's excluded account billing. No ChargeDesk or payment-provider configuration was changed or live plugin exercised.

The old SDK receives only from its baked localhost/test/production/staging allowlist, including https://app.happytohelp.com, and sends to *. Preserving the eventual https://app.happytohelp.com origin where feasible helps that allowlist, but does not by itself qualify protocol/data compatibility.

Migrate a controlled plugin to createPluginClient({hostOrigin}) from src/modules/plugin-sdk/index.ts, optionally assigning it to window.HappytoHelp. hostOrigin must be the exact native application origin (scheme, host and port; no path, trailing slash or wildcard), for example https://support.example.com. The dashboard configures each iframe's exact pluginOrigin from its URL. Receivers check both origin and sending window; outbound messages use that explicit origin. HTTP is accepted only for localhost. The preserved envelope is {happytohelp:true,type,payload} with setMessageContent, getConversation/setConversation, resolveConversation and setHeight. Payload/height bounds and current native conversation permission still apply. Arbitrary sendEvent types are not a native capability grant.

Inventory plugin URL, owning project, deployed SDK revision, expected host origin, command/data dependencies and responsible external maintainer. Migrate and qualify draft insertion, conversation context, resolution and sizing for each used plugin before moving that caller. External plugins still baking the legacy host list must be updated by their maintainer or kept on legacy.

Widget hash

The public project key identifies the installation; it is not a credential. Generate visitor identity and metadata signatures only on the customer's trusted backend with that workspace's secret, and preserve the native verifier's exact canonicalization. An identity hash from an unrelated installation is not portable authority. Never place workspace secrets, dashboard tokens or old JWTs in public snippets. Follow the current Widget > Code verification examples and the identity module's verifier when updating a customer integration.

Values

Keep project IDs/public keys, published project/article slugs, conversation IDs, mailbox plus addressing and retained file identity consistent in the reviewed import. Native client preferences may change appearance and copy; they cannot relax origin checks, grant membership, publish drafts or make private files public. Unknown exported hosts and pending external outcomes remain explicit inventory items rather than invented defaults.

Safety

The owner-controlled switch requires a consistent authorized export and delta window, retained bytes with hashes and visibility, exact website/help/plugin/mail host inventories, DNS/TLS/account access, configured native provider consent and explicit production cutover approval. Until then, keep legacy authoritative for all Drain rows. Do not replay uncertain sends, crawls, jobs or OAuth exchanges. The new source can be prepared and exercised locally without changing production.

Old public resource paths

Preserve these six links with narrow documentation mappings when the owner moves the public routing. Native source implements GET/HEAD-only HTTP 308 redirects to this migration guide. The approved homepage and retired marketing/legal/pricing/waitlist flows are outside this mapping.

Only these named GET/HEAD resource paths (with optional trailing slash) are part of this mapping. Do not use a broad /resources/* redirect to mask unknown legacy resources or reinterpret POSTs.

Source trace

Legacy sources below were read-only. Paths are relative to their original repositories under chargedesk/, not runtime dependencies of this native release.

Production use, complete installed caller inventory, original storage/domain ACLs and external plugin compatibility remain unverified until the owner's cutover artifacts and provider evidence exist.