Skip to main content
All docs

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, and floating invitation note without requiring a snippet reinstall.

  • 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-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"
  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.
<button onclick="window.PorchlightWidget.open()">Book a consult</button>

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&url=https%3A%2F%2Fbook.example.com%2Fsite-visit

Preserve campaign and referrer fields when available:

https://app.getporchlight.ai/embed/your-org-slug?source=google_profile&campaign=site-visit&host=book.example.com&path=/site-visit&url=https%3A%2F%2Fbook.example.com%2Fsite-visit%3Futm_source%3Dgoogle_profile%26utm_campaign%3Dbooked_consult&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 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, url, source, and campaign fields. Use Domain allowlist and customer consult URLs for the full checklist.

Verifying it works

  1. Load a page with the snippet.
  2. Open the bubble.
  3. Send a test message.
  4. Confirm the conversation lands in the Porchlight Inbox.
  5. 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.
  6. Confirm the handoff detail includes host, path, campaign, referrer, and full URL when the source supplied them.

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.

Article feedback

Did this solve the issue?