Buyer surfaces

Use hosted intake links immediately, then install the website widget when the customer or their web person is ready. The widget loads asynchronously, does not block the page, and works on CMS sites like WordPress, Wix, Squarespace, Webflow, Shopify, GoDaddy, Duda, Google Tag Manager, and custom HTML. Customer-domain redirects use source-safe attribution so untrusted hosts cannot claim another customer's traffic.

Porchlight has three buyer-facing entry points:

Website embed: a chat bubble on the customer's existing site.
Tracked consult link: a Porchlight-hosted URL for Google Profile, campaigns, QR codes, mailers, sales follow-up, and temporary launches.
Customer-domain tracked consult link: a customer-owned URL such as https://book.example.com/site-visit or https://example.com/start that redirects to Porchlight with source context.

All entry points mint the same web session token, use the same agent, create the same conversation and lead records, and preserve source metadata on the conversation.

Website embed

<script
  src="https://app.getporchlight.ai/widget.js"
  data-org="your-org-slug"
  data-source="website_widget"
  async
></script>

Replace your-org-slug with the slug of your Porchlight organization. You can find it in Settings -> Branding or in the URL of your dashboard.

Choose the launch path

During onboarding, Porchlight stores the preferred buyer-facing launch path:

Hosted intake first when the customer is not technical, does not know who edits the website, or wants to launch from Google Business Profile, a campaign, or sales follow-up before touching the main site.
Send to web person when a website manager, freelancer, or agency owns the site. The Launch page generates an email with the snippet, hosted fallback URL, and platform-specific steps.
Existing site widget when the owner or team has confirmed CMS access.

The dashboard treats tracked consult links as valid buyer surfaces. The widget install check only becomes required when the customer chooses the existing-site route.

Where to paste it

Put the snippet just before the closing </body> tag on every page where the chat bubble should appear. Most customers add it site-wide, then use page context and button copy to steer buyers into the right consult flow.

Common CMS paths:

WordPress: use a header/footer script plugin or the theme footer editor, then clear cache.
Wix: Settings -> Custom Code -> Body - end -> all pages, then publish.
Squarespace: Settings -> Advanced -> Code Injection -> Footer.
Webflow: Site settings -> Custom code -> Footer code, then publish to production.
Shopify: Online Store -> Themes -> Edit code -> theme.liquid, before </body>.
GoDaddy/Duda: use the site's Custom Code, Footer HTML, or Body end area.
Google Tag Manager: create a Custom HTML tag with an all-pages trigger.

Configuration options

Most widget appearance settings are managed in Porchlight under Settings -> Branding. Installed widgets refresh the saved avatar, theme, starter prompts, launcher label, and floating invitation note without requiring a snippet reinstall. The persistent launcher label defaults to Ask a question and stays visible on desktop even when the optional invitation note is disabled or dismissed. On compact mobile viewports, the launcher uses the icon alone.

The automatic desktop invitation opens after the configured delay, remains visible for twelve seconds, and then collapses. Incidental pointer movement does not close a timed invitation. Opening the widget ends automatic invitations for that page session; explicitly closing the invitation creates a seven-day cooldown. Automatic invitations are disabled on compact mobile viewports.

data-org is required.
data-position can be bottom-right or bottom-left.
data-attention-enabled can be false to hide the callout for this specific embed.
data-attention-text overrides the saved callout above the bubble, such as Book a backyard project consult.
data-attention-delay overrides the saved callout delay in milliseconds.
data-launcher-image-url replaces the standard chat icon with a circular team photo, logo mark, or other small image.
data-launcher-image-alt labels the launcher image for the settings preview and button accessibility copy.
data-launcher-label overrides the saved persistent launcher label with up to 24 characters.
data-launcher-label-enabled can be false as an advanced escape hatch when the host site supplies an equally clear launcher label.
data-source labels where the conversation came from. Use website_widget, campaign, google_profile, booking_link, manual, or a short custom label.
data-campaign is optional and is stored with the conversation source.

<script
  src="https://app.getporchlight.ai/widget.js"
  data-org="your-org-slug"
  data-source="campaign"
  data-campaign="spring-service-area-page"
  data-position="bottom-right"
  data-attention-enabled="true"
  data-attention-text="Book a qualified consult"
  data-attention-delay="6000"
  data-launcher-image-url="https://example.com/team-member.jpg"
  data-launcher-image-alt="Mia from Pacific Sauna Works"
  data-launcher-label="Ask Mia"
  async
></script>

Programmatic control

The loader exposes window.PorchlightWidget:

window.PorchlightWidget.open() opens the chat panel.
window.PorchlightWidget.close() closes it.
window.PorchlightWidget.toggle() toggles it.
window.PorchlightWidget.startNewConversation() opens the widget and uses

the same guarded restart flow as the header menu. Meaningful history or an unsent draft requires visitor confirmation, and an in-flight reply or unresolved project submission prevents restart until its outcome is known.

window.PorchlightWidget.refreshPageContext() re-reads the browser's current

host and canonical pathname and sends it to an open widget.

window.PorchlightWidget.updatePageContext({ path: "/products/model" })

supplies a same-host canonical path for routers the loader cannot observe. Protocols, external hosts, query strings, fragments, and control characters are rejected or removed.

<button onclick="window.PorchlightWidget.open()">Book a consult</button>

A demo or sandbox page can wire its visible restart control without depending on a tenant-specific scripted scenario:

<button onclick="window.PorchlightWidget.startNewConversation()">
  Start a new test
</button>

startDemo() and resetDemo() remain available for scripted recording fixtures. Use startNewConversation() for production widgets and real-model sandboxes so session, resume, draft, upload, consent, and submission state are reset together.

Page awareness and trusted mappings

Page awareness is off by default for existing organizations. An owner or admin can enable it under Settings -> Knowledge base after reviewing the customer-site routes that should participate.

For every page-aware route:

Add the exact canonical path, such as /services/installation, to one

approved knowledge entry.

Avoid wildcard or host-based mappings. A path that maps to more than one

entry fails closed as ambiguous.

Review the built-in sensitive exclusions. Auth, account, admin, cart,

checkout, payment, and form-confirmation path families never contribute model context.

Add narrower tenant exclusions for private intake, client portal, or other

site-specific route families.

Test a normal page, an unmapped page, a sensitive page, and an SPA route

change before launch.

The route is an untrusted hint. Porchlight uses it only to select a tenant-scoped knowledge entry; the knowledge lookup still supplies the facts. Explicit visitor language always takes priority over what page they are on.

Most SPAs are detected automatically through pushState, replaceState, popstate, and hashchange. Use refreshPageContext() after a custom router transition, or updatePageContext({ path }) when the router does not expose the new path to the loader.

Tracked consult links

Use tracked consult links for Google Profile, dealer profiles, QR codes, mailers, campaigns, and sales follow-up. These links are not a replacement website. They are source-tagged entry points into the same qualification and handoff flow.

Examples:

https://app.getporchlight.ai/embed/your-org-slug?source=hosted_page
https://app.getporchlight.ai/embed/your-org-slug?source=google_profile&campaign=profile-appointment&utm_source=google_profile&utm_medium=organic&utm_campaign=booked-consult
https://app.getporchlight.ai/embed/your-org-slug?source=campaign&campaign=offline-qr-mailer&utm_source=offline&utm_medium=qr_mailer&utm_campaign=consult

Customer-domain tracked consult link

Use a customer-domain tracked consult link when the customer wants their own domain in front of a production website CTA, Google Business Profile, dealer profile, QR code, mailer, or campaign. The customer-owned URL stays buyer-facing; Porchlight handles the agent and handoff.

In Settings -> Branding, save:

Customer consult URL, for example https://book.example.com/site-visit.
Redirect host, for example book.example.com.
Redirect path, for example /site-visit.
Any additional exact source hosts that may embed the widget or redirect to this page.

Then configure the customer's DNS, proxy, CMS redirect, or lightweight hosted page to send buyers to:

https://app.getporchlight.ai/embed/your-org-slug?source=customer_domain&host=book.example.com&path=/site-visit

Preserve only allowlisted campaign fields when available:

https://app.getporchlight.ai/embed/your-org-slug?source=google_profile&campaign=site-visit&host=book.example.com&path=/site-visit&utm_source=google_profile&utm_campaign=booked_consult

Porchlight only accepts claimed customer-domain hosts that are configured for the org. If the host is missing from Settings, the session is denied instead of minting a token with untrusted source metadata.

The loader never sends or stores the page query string, fragment, document title, or full referrer URL as agent context. It retains only the approved host, canonical pathname, normalized referrer host, and the fixed UTM allowlist.

The hosted intake page displays business branding, product lines, service categories, service areas, FAQs from the knowledge base when available, and the Porchlight agent inline. It does not pretend to be a proof gallery or full website.

Troubleshooting

If the bubble does not appear, check the browser console for a typo in data-org, an inactive org, or a Content Security Policy that blocks the Porchlight domain.

For a step-by-step launch checklist, use Website widget is not showing. If the bubble appears but the panel is blank, use Blank widget panel or CSP block.

If Verify install reports a blocked host, add that exact customer website host in Settings -> Branding and verify again. Onboarding automatically allows the host from the website URL when it is available, including the matching apex or www variant.

If the panel is blank, add frame-src https://app.getporchlight.ai to the site's CSP.

If a customer-domain consult link opens but the chat does not start, confirm the exact host is saved in Settings -> Branding and that the redirect forwards the host, path, source, and allowlisted campaign fields. Use Domain allowlist and customer consult URLs for the full checklist.

Verifying it works

Load a page with the snippet.
Open the bubble.
Send a test message.
Confirm the conversation lands in the Porchlight Inbox.
Open the conversation or lead handoff and confirm the Source field shows the expected website, customer-domain consult link, hosted intake, Google profile, booking link, manual, or campaign label.
Navigate to a second page without reloading, send another message, and

confirm the conversation keeps its entry page while the current canonical path advances. Query strings, fragments, titles, and full referrer URLs must not appear.

Open the conversation in Inbox and confirm entry page, current page,

last route change, and trusted grounding status are correct.

Once a buyer chats, Porchlight qualifies the project, records the lead, and moves ready buyers toward a consult, showroom visit, design call, or site visit.