Widget Integration Guide

Embed Echoback testimonial widgets on any website with a single <iframe>. Widgets are server-rendered for fast loading — no JavaScript bundle required.

Quick Start

Copy the iframe snippet from your widget's Embed Codes tab in the Echoback dashboard. It looks like this:

<iframe
  src="https://api.echoback.co/functions/v1/widget-embed?widgetId=YOUR_WIDGET_ID"
  width="100%"
  height="500"
  style="border: none;"
></iframe>

The embed is server-rendered HTML — the response includes all feedback data and styling inline. No external scripts are loaded (except a small inline script for carousel navigation). Responses are cached for 5 minutes.

Silent Mode

By default, the widget displays a user-visible error message when loading fails (e.g. invalid widget ID or widget not found). If you prefer a blank iframe on error, append &silent=1:

<iframe
  src="https://api.echoback.co/functions/v1/widget-embed?widgetId=YOUR_WIDGET_ID&silent=1"
  ...
></iframe>

In silent mode the iframe renders a transparent, empty page on error instead of an error message. You can detect errors by checking the iframe's HTTP status (400 for invalid ID, 404 for not found, 500 for server error).

Load Detection

When the widget finishes rendering inside the iframe, it sends a postMessage to the parent page. This is more reliable than the iframe load event, which some browsers (notably Safari) fire inconsistently for cross-origin iframes.

window.addEventListener("message", (event) => {
  if (event.data?.type === "echoback-widget-loaded") {
    // event.data.widgetId contains the widget UUID
    console.log("Widget loaded:", event.data.widgetId);
    // Show the iframe container, remove skeleton, etc.

    // Optional: send ack to stop retries
    const iframe = document.querySelector("iframe");
    if (iframe?.contentWindow) {
      iframe.contentWindow.postMessage({ type: "echoback-widget-ack" }, "*");
    }
  }
});

The widget retries the load message a few times to handle cases where your listener isn't set up yet. Send back an echoback-widget-ack message to stop retries (optional — extra pings are harmless).

Security

Content Security Policy

If your site uses a Content-Security-Policy header, add the Echoback API domain to the frame-src directive:

frame-src 'self' https://api.echoback.co;

Sandbox Attribute

Do not add a sandbox attribute to the iframe. Safari blocks cross-origin sandboxed iframes from loading, which will cause the widget to appear blank. The embed is server-rendered static HTML and does not need sandboxing.

Responsive Tips

Set width="100%" and wrap the iframe in a container that controls its max width. Use a fixed height appropriate for the widget type:

A responsive wrapper pattern:

<div style="max-width: 720px; margin: 0 auto;">
  <iframe
    src="https://api.echoback.co/functions/v1/widget-embed?widgetId=YOUR_WIDGET_ID"
    width="100%"
    height="500"
    style="border: none;"
  ></iframe>
</div>