Widget Integration

Three ways to add Orac to your site — from simple to advanced.

Script Tag (Universal)

The simplest method. Works on any website — HTML, WordPress, Shopify, Webflow, Squarespace, Wix, and more. Copy the script tag from your project's Embed tab and paste it before the closing </body> tag.

<script
  src="https://askorac.com/widget.js"
  data-orac-id="your-project-id"
  defer
></script>

The widget loads asynchronously and won't slow down your page. It renders in an isolated iframe, so your site's CSS never conflicts with the widget's styles.

Configuration Attributes

Customize the widget behavior using data attributes on the script tag:

<script
  src="https://askorac.com/widget.js"
  data-orac-id="your-project-id"
  data-orac-theme="auto"
  data-orac-context="User is on the pricing page. Plan: Pro."
  data-orac-visitor-token="jwt-token-here"
  defer
></script>

data-orac-id (required) — your project ID from the dashboard.

data-orac-theme — “light”, “dark”, or “auto” (follows system preference). Default: “auto”.

data-orac-context — additional context passed with every message. Use this for in-app support to tell Orac what page the user is on, their plan, or their current state. The widget already sends the page URL automatically — this attribute adds extra context.

data-orac-visitor-token — authentication token for logged-in users. This token is forwarded to your custom action webhooks as an X-Visitor-Token header, enabling personalized API responses. Orac never stores or processes this token.

WordPress

Two methods depending on your setup:

Method 1: Theme editor — Go to Appearance → Theme Editor → footer.php. Paste the script tag before </body>.

Method 2: Plugin — Install a header/footer script plugin (like “Insert Headers and Footers”). Paste the script tag in the footer section.

For WordPress sites, we recommend using full site crawl to train Orac. It automatically discovers all your posts and pages via your sitemap.

Shopify

Go to Online Store → Themes → Edit Code → Layout → theme.liquid. Paste the script tag before the closing </body> tag.

For Shopify stores, crawl your entire catalog so Orac can answer product-specific questions with accurate pricing and availability info.

Webflow

Go to Project Settings → Custom Code → Footer Code. Paste the script tag. Publish your site for the change to take effect.

React / Next.js

For React applications, you can use the script tag approach in your root layout or HTML file. In Next.js App Router:

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://askorac.com/widget.js"
          data-orac-id="your-project-id"
          data-orac-theme="auto"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

REST API

For full programmatic control, use the chat API directly:

// POST /api/chat
const response = await fetch("https://askorac.com/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    project_id: "your-project-id",
    message: "How does pricing work?",
    visitor_id: "unique-visitor-id",
    page_url: "https://yoursite.com/pricing"
  })
});

// Response is a Server-Sent Events stream
const reader = response.body.getReader();
// Read SSE events: { type: "text", content: "..." }
// Final event: { type: "sources", sources: [...] }

The API returns a Server-Sent Events (SSE) stream. Events include text (response chunks), sources (citation URLs), confidence (quality score), and tools_used (if actions were triggered).

Testing

After embedding, test the widget by asking a question that you know your content answers. Check:

1. Does the widget appear in the correct position (left/right)?

2. Does the response cite the correct source page?

3. Does the theme match your site (light/dark)?

4. On mobile, does the widget take full screen when opened?

If the widget doesn't appear, check the browser console for errors. The most common issue is an incorrect project ID.