Install the website widget

Choose one installation path#

Start in your Reesponder workspace, open Websites, then select the website. Its Installation tab presents a method based on the detected platform. A normal Shopify storefront uses a snippet in the published theme. WordPress uses the Reesponder plugin. A custom website or another content management system uses the HTML snippet in a shared public layout.

Use one method per website. If the WordPress plugin already supplies the script, do not also paste it into a theme footer or a tag manager. If an existing Shopify app connection owns the installation, the portal identifies it and tells you to keep its app embed. To switch that connection to a manual snippet, uninstall the app in Shopify first and refresh the website view.

The task has three separate outcomes: the script is published, the service detects a valid installation, and a visitor receives a useful answer. You will verify each one below. Preparing Knowledge is a parallel task; a completed crawl does not put the widget on the website.

Prepare the public domain and workspace#

You need permission to manage the Reesponder workspace and permission to publish the website. The workspace needs active access and available website capacity. To add a website, choose Websites → Connect a domain, enter Website name and Domain, then select Start automatic setup. Use a recognisable business name and the customer-facing hostname.

For example, if customers finish a redirect on www.example.com, register that hostname, not example.com simply because it is shorter. They are different hostnames. An administrator address, a theme preview and shop.example.com are also different origins. Do not assume the installation authorises every subdomain. The domain field is not a product URL: omit page paths, port numbers and local development addresses.

Open the intended site in a fresh browser tab and check the address after redirects. Use the public HTTPS address throughout these checks. If you need another hostname, staging environment or a domain migration, review domain binding before copying production code. Do not bypass an origin rejection by changing the public site ID or inventing a token.

Generate and copy the complete snippet#

For a manual installation, select Generate installation code, then Copy installation code. On Shopify, the initial control is Generate & copy code. Copy the entire script element, including its closing tag. The portal generates the public site ID and current installation token together for the selected website.

This is the exact supported shape, with example placeholders. Do not paste these placeholders into a live website. Use the complete code displayed in your own workspace; nothing inside the generated snippet needs to be edited.

<script
  src="https://cdn.reesponder.com/widget/v1/reesponder.js"
  data-site-id="YOUR_PUBLIC_SITE_ID"
  data-installation-token="YOUR_CURRENT_INSTALLATION_TOKEN"
  defer></script>

The installation token belongs in this browser script, but it is not a general account API key. Never add a workspace session, WordPress management token or private integration credential to the page. If clipboard access is blocked, select and copy the displayed code manually. Keep the attributes and ordinary straight quotation marks intact: a rich-text editor can turn code into visible text or replace quotation marks with typographic ones.

Place it in a shared public layout#

Find the template that produces the final HTML for your public pages. Paste the snippet on its own line immediately before the closing </body> tag. Keep all existing page code. This location lets the same installation cover every page using that layout without copying a script into individual products or articles.

In a visual website builder, use its supported custom HTML or footer-code field, not a paragraph block. Confirm whether that field is global or page-specific. In a server-rendered application, use the root HTML layout or the framework's supported external-script mechanism so the original attributes reach the script element. Check the rendered result rather than assuming the component name guarantees execution.

For client-side navigation, load the widget once in the persistent layout. Do not append another script every time the route changes. The official loader creates a single widget host per document, but multiple installation paths still leave unnecessary requests and make later replacements confusing. For a full page load, each public layout must include the snippet. Keep a record of the exact template or configuration field you changed.

<body>
  <main>Your existing page</main>
  <footer>Your existing footer</footer>

  <!-- Paste your complete Reesponder snippet here -->
</body>

Shopify: edit the current theme#

In the website's Installation tab, generate and copy your snippet, then choose Open Shopify themes. Check that you are in the Shopify store corresponding to the registered domain. On the Current theme, open … → Edit code, select layout/theme.liquid, and search for </body> with Ctrl or ⌘ + F.

Paste the generated code immediately above that closing tag and select Save. Add it once to the layout. Do not replace the existing footer, delete theme scripts or insert another copy in a product template. Open the actual public storefront, unlock its password page if necessary, and reload. Saving a draft theme or opening a theme preview is not proof that shoppers receive the installation.

Pages using a custom layout may need the snippet in that layout too. Shopify checkout and new customer-account pages use separate systems and are not covered by this theme installation. A headless storefront needs the snippet in its own website layout. Installing the launcher also does not grant private order access; that needs a separately authorised integration. See the Shopify guide for platform-specific details.

WordPress: connect, then enable#

The plugin requires WordPress 6.3 or later, PHP 8.0 or later and a single-site installation. WordPress administration and the public website must share a hostname, use HTTPS, and the theme must call wp_footer(). A subdirectory installation is supported. Check those conditions before troubleshooting a connection that cannot complete.

Download the plugin ZIP from Reesponder's Installation tab. In WordPress, open Plugins → Add New Plugin → Upload Plugin, upload the ZIP, select Install Now, then Activate. Open Reesponder in the WordPress sidebar and select Connect Reesponder. Sign in to Reesponder, approve the matching website in the intended workspace, and return to WordPress.

A completed connection is initially disabled. Select Enable widget, clear any page cache, then open the public website. Return to the plugin and choose Check connection to confirm detection. If the approval flow expires, restart Connect rather than reuse an old approval URL. Do not paste an additional manual snippet. The plugin installs the widget; it does not request WooCommerce orders or turn private store records into Knowledge. The WordPress guide explains reconnecting and removal.

Publish the change customers will receive#

Finish the website's normal publishing process after editing the layout. A saved source file, successful local build or editor preview can all exist without changing the deployed public HTML. If your platform distinguishes Save from Publish, complete both. Confirm the live hostname and active theme or deployment before inspecting Reesponder status.

Clear the page cache and CDN cache for affected pages when your platform uses them. A new token in the template does not help a visitor who still receives cached HTML containing the old one. Script optimisers can also delay the loader until an interaction, combine it with other scripts or change how its attributes are handled. If that happens, exclude the official script from that transformation using your optimiser's own controls.

Inspect the actual browser page for cdn.reesponder.com/widget/v1/reesponder.js and its two data attributes. An injected builder script may appear in the live Elements tree even if it is absent from View Source, so also inspect Network. The decisive evidence is that the current public page executes the correct script; a line in a source repository is only one part of that chain.

Prove a fresh public installation check#

Open the registered public domain and reload the page. The loader sends an installation check without requiring a chat message. In Reesponder, the website summary changes from Installation pending to Widget detected, and Last seen shows the time of a valid check. The website view refreshes periodically while installation or crawling is pending; you can also use its refresh control.

Check the timestamp as well as the label. A website that was detected earlier can retain Widget detected after replacement code is generated. The label alone therefore does not prove the newly published token works. Reload the live page after publishing and confirm that Last seen advances beyond your deployment time.

A detection success proves that this domain reached the service using the current site ID and installation credential. It does not prove that customer questions can be answered, that all routes include the snippet, or that private Actions are connected. The greeting is rendered by the widget, so opening the panel and seeing a welcome message is also insufficient. Send a representative question for the next level of verification.

Read the browser's request sequence#

For a precise check, open Developer Tools, select Network, keep the log visible and reload. Filter for reesponder. First confirm that the browser loads https://cdn.reesponder.com/widget/v1/reesponder.js. Next look for POST /v1/widget/installations/detect on https://api.reesponder.com. A successful response returns the website's current widget configuration.

On the first message of a new conversation, expect POST /v1/widget/bootstrap, followed by a messages request under /v1/widget/conversations/…/messages. A conversation already present in that browser tab may reuse its ID, so a bootstrap request is not required on every message. Opening the chat alone does not bootstrap a conversation. A request labelled blocked by a browser or a CSP violation is different from an API response with a status code.

Inspect the failing request's status and response before changing anything. A detect rejection usually calls for checking the final hostname and current snippet; a successful detection followed by an access failure calls for workspace access and capacity checks. Repeated rapid reloads or submissions can encounter rate limits. Keep a redacted screenshot of the failed request, not a public export containing all cookies, tokens and visitor messages.

Verify answers against your business information#

Open the website's Knowledge tab. Review crawl progress, processed pages, available documents and any reported errors. A crawl can finish without capturing a password-protected page or every detail you need. Check the actual sources and add missing business facts before accepting a launch based on a document count alone.

Prepare three questions with known outcomes: one about the page currently open, one about a clear published policy, and one the business cannot answer from available information. Compare each answer with its source. For example, a delivery question should reflect the actual delivery policy; a request for an unsupported service should receive an honest limitation rather than a made-up offer.

The Private test tab creates a five-question preview using current Knowledge without consuming customer conversations. It is useful for reviewing content and language, but it does not reproduce the live page context, customer identity, connected Actions or human handoff. Verify those through the public widget separately. Live tests follow normal usage rules. If the private preview works but live messages fail, investigate the installation or public conversation path instead of repeatedly rewriting Knowledge.

Test the routes your customers use#

Make a small route checklist: homepage, a representative product or service page, a policy page, and a contact or enquiry page. Open each directly in a fresh tab, not only by clicking from the homepage. Direct entry catches layouts or server routes that do not inherit the global script.

Then navigate between two important pages in the same tab and ask a page-specific question after moving. The widget sends the current path and query with messages, and the service uses available Knowledge for that path. A correct page address cannot compensate for missing or outdated source content. Compare the answer with what that route actually offers.

For an application with client-side navigation, test both a direct full load and an internal route change. Confirm that navigation neither removes the widget nor injects another loader. Also test any custom layout that intentionally differs from the rest of the website. Do not treat visible transcript restoration after reload as an installation requirement: the current widget can preserve conversation identifiers without rebuilding the full previous transcript in the panel. Storage continuity and current-page accuracy are separate checks.

Check mobile, keyboard and surrounding controls#

Test on an actual phone as well as a narrow desktop viewport. Open the widget, type with the on-screen keyboard, send a message, scroll the conversation, and close it again. Confirm that the composer remains usable and closing returns you to a usable website. A desktop screenshot cannot reveal every mobile keyboard and browser-bar interaction.

Check the launcher beside cookie controls, a sticky checkout button, a floating navigation bar and any other fixed element your site uses. Test the page when each surrounding overlay is open. Look for controls that become covered or impossible to tap, rather than considering the widget alone in an otherwise empty viewport.

On desktop, use the keyboard to reach the launcher, open the panel, enter a question and close it. Inspect visible focus and practical reading order. If you use a screen reader, run the same route and question rather than assuming native buttons establish accessibility for the entire combined page. Appearance changes should preserve readable contrast. These are launch checks, not a certification claim; your site's own overlays and custom styles can affect the combined experience.

Review security policies and browser storage#

If the website has a Content Security Policy, the loader needs permission to load from https://cdn.reesponder.com and communicate with https://api.reesponder.com. Review the applicable script-src and connect-src directives with the person responsible for that policy. A configured avatar may also require its own HTTPS image origin.

The current widget uses a closed Shadow DOM, not an iframe, and creates its own style element and dynamic style values. A restrictive style policy therefore needs compatibility review too. There is no universal CSP header to copy from this guide and no supported snippet nonce setting to invent. Use the browser's exact violation message to identify the blocked resource or operation; do not disable the entire policy to hide the error.

The widget uses first-party browser storage for visitor, tab and conversation continuity. Your website's consent manager and disclosures are your own integration responsibilities; installing Reesponder does not automatically configure them. If a policy intentionally delays the widget, test both sides of that decision and explain the expected availability. Reesponder's marketing analytics are not automatically installed on a customer's website by this snippet. See storage and continuity for the boundaries.

Replace code deliberately and preserve working installs#

Saving settings in Appearance does not change the installation token. Reload the public page to see the saved appearance; do not generate a replacement snippet for a colour or name change. When changing a Shopify theme or website layout, move the existing working snippet into the new published layout and repeat detection and route checks.

Generating replacement installation code invalidates the previous token immediately. On a verified manual installation, the control becomes Replace manual installation code and asks you to confirm the replacement. Prepare access to every template, custom layout and deployment that uses the old snippet before confirming. Replace all those copies, clear cached HTML and prove a fresh Last seen timestamp.

Do not roll back to an old deployment containing the revoked token and expect it to work. A code rollback needs the current valid snippet. When migrating from a plugin or existing app connection, follow that integration's disconnection path rather than mixing installation owners. To remove the assistant permanently, remove its publishing path and use the website's Settings workflow to revoke the website credentials when appropriate. Disabling a plugin alone is not the same as revoking its remote connection.

Diagnose by the first failing check#

Work from the first failed step rather than generating new code repeatedly. The table below connects observable evidence to the next useful action.

If the problem remains, give support the public hostname, installation method, failing page path, time of the test and failing request's status. Include a redacted Console or Network screenshot and explain whether private Knowledge tests and public messages behave differently. Do not post account cookies, private credentials, full conversation transcripts or unredacted network exports. For the full visible-widget diagnostic path, continue to Widget not visible.