API endpoints

Three public endpoints power the embedded widget. They live under https://wiqly.io/api/widget/{embedToken}.

Each is tied to a widget's embed_token (the value of data-widget-id on the embed script). No additional auth.

GET /api/widget/{embedToken}

Returns the widget's configuration: name, character, background, welcome video URL, FAQ list with their video URLs and CTA configuration.

Use case: the widget script calls this on load to render the visitor experience. You can also call it server-side if you need to inspect what a widget exposes.

Response shape (abbreviated):

{
  "id": "widget-id",
  "name": "Pricing page widget",
  "welcome": {
    "script": "...",
    "video_url": "https://cdn.wiqly.io/...",
    "cta": { /* CTA config */ }
  },
  "questions": [
    {
      "id": "faq-id",
      "label": "What's your refund policy?",
      "video_url": "https://cdn.wiqly.io/...",
      "status": "ready",
      "cta": { /* CTA config */ }
    }
  ],
  "character": { "id": "...", "name": "...", "thumbnail": "..." },
  "background": { /* background config */ }
}

status on a question is one of pending, generating, ready, or failed. Only ready videos play; the rest render as "Soon" in the menu.

POST /api/widget/{embedToken}/events

Accepts an analytics event from the widget. Open to cross-origin requests (CORS).

Body:

{
  "event_type": "widget_opened",
  "faq_item_id": "optional-faq-id-when-relevant",
  "session_id": "anonymous-session-id"
}

Event types: widget_loaded, widget_opened, faq_clicked, video_completed, lead_captured. See Analytics events for full semantics.

Rate-limited per-IP to prevent abuse. The widget script handles batching and retry automatically.

POST /api/widget/{embedToken}/leads

Accepts a lead capture from the widget. Fires any configured webhook and email notification.

Body:

{
  "faq_item_id": "the-faq-they-watched",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+44 20 1234 5678",
  "message": "Optional message"
}

email is required. name, phone, and message are optional. faq_item_id should be set when the submission came from a question's CTA (vs the welcome video's CTA).

Response: { "ok": true } on success. The webhook to your CRM is dispatched fire-and-forget, so the response returns fast regardless of your endpoint's speed.

CORS

All public widget endpoints accept cross-origin requests from any domain. We don't restrict embedding — your widget should work wherever you put the script tag.

Rate limiting

We rate-limit per-IP on the events and leads endpoints to prevent abuse. Normal usage will never trip the limit. If you're load-testing or scripting, get in touch and we'll work out an allow-list.