Embedding Widgets

oHallo provides embeddable widgets that let your website visitors search your knowledge base, submit inquiries, or book meetings — without leaving your site. Widgets are lightweight JavaScript components that load asynchronously and work on any website.

A search interface that lets visitors find answers from your oHallo knowledge base. The visitor types a question, and the widget returns matching KB entries with relevant excerpts. This can deflect support requests by giving visitors instant answers.

A structured form that lets visitors submit an inquiry. The submission creates a new conversation in oHallo, routed to the appropriate workspace and channel. You can configure which fields to show (name, email, subject, message, category).

A multi-step form that lets visitors book a meeting with your team. The widget walks the visitor through four steps: filling in contact details, picking a date, selecting an available time slot, and confirming the booking. oHallo creates a tentative calendar event, sends the visitor a confirmation email, and once they confirm, adds a conferencing link (Google Meet or Microsoft Teams) to the event.

Open the oHallo dashboard.
Go to Settings then Widgets.
Click + New Widget.
Choose the widget type: Knowledge Base, Contact Form, or Booking.
Configure the widget:
- Name: An internal label (e.g. “Support KB Widget”).
- Workspace: The workspace whose KB entries should be searchable, or where form submissions should be routed.
- Appearance: Primary colour, position on the page (bottom-right or bottom-left), and whether the widget starts open or collapsed.
- Calendar connection (Booking only): Which connected calendar to use for availability and events.
- Slot duration (Booking only): Meeting length — 15, 30, 45, or 60 minutes.
Click Create. oHallo generates a widget ID and embed code.

Getting the embed code

After creating a widget, you will see an embed code snippet on the widget’s settings page. It looks like this:

<script
  src="https://widget.ohallo.eu/embed.js"
  data-widget-id="wgt_abc123"
  data-position="bottom-right"
  data-primary-color="#0F62FE"
  async
></script>

Copy this snippet. You will add it to your website in the next step.

Paste the embed script into your HTML, just before the closing </body> tag:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <header>
    <h1>Welcome to Acme Corp</h1>
  </header>
  <main>
    <p>Your website content here.</p>
  </main>

  <!-- oHallo Widget -->
  <script
    src="https://widget.ohallo.eu/embed.js"
    data-widget-id="wgt_abc123"
    data-position="bottom-right"
    data-primary-color="#0F62FE"
    async
  ></script>
</body>
</html>

The widget loads asynchronously and does not block your page rendering. It appears as a small button in the specified corner of the page.

Frameworks and SPAs

For React, Vue, Next.js, or other single-page applications, add the script tag to your root HTML file (e.g. index.html or _document.tsx). The widget handles client-side navigation automatically.

React / Next.js — add to pages/_document.tsx or app/layout.tsx:

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <script
          src="https://widget.ohallo.eu/embed.js"
          data-widget-id="wgt_abc123"
          data-position="bottom-right"
          data-primary-color="#0F62FE"
          async
        />
      </body>
    </html>
  )
}

Static site generators (Astro, Hugo, Jekyll) — add the script to your base layout template.

The booking widget uses a different script and renders inline within a target element rather than as a floating button. Add a container element and the script tag:

<div id="ohallo-booking"></div>
<script
  src="https://widget.ohallo.eu/booking.js"
  data-key="your-public-key"
  data-target="ohallo-booking"
  async
></script>

The data-key attribute is the widget’s public key (visible on the widget settings page). The data-target attribute is the ID of the DOM element where the widget mounts.

React / Next.js:

export default function BookingPage() {
  return (
    <div>
      <h1>Book a meeting</h1>
      <div id="ohallo-booking" />
      <script
        src="https://widget.ohallo.eu/booking.js"
        data-key="your-public-key"
        data-target="ohallo-booking"
        async
      />
    </div>
  )
}

Astro:

<div id="ohallo-booking"></div>
<script
  src="https://widget.ohallo.eu/booking.js"
  data-key="your-public-key"
  data-target="ohallo-booking"
  async
></script>

Unlike the KB and Contact Form widgets, the booking widget’s appearance (variant, colours, theme) is configured entirely in the dashboard. The embed code only needs the public key and target element.

Customising appearance

The following attributes apply to Knowledge Base and Contact Form widgets. Booking widget appearance is configured in the dashboard.

You can customise the widget’s appearance using data-* attributes on the script tag:

Attribute	Default	Description
`data-position`	`bottom-right`	Widget position: `bottom-right` or `bottom-left`
`data-primary-color`	`#0F62FE`	Primary colour for the button and header (hex format)
`data-text-color`	`#FFFFFF`	Text colour on the button and header (hex format)
`data-greeting`	(none)	A short greeting shown when the widget opens, e.g. “How can we help?”
`data-start-open`	`false`	Set to `true` to open the widget automatically on page load

Example with custom colours and greeting:

<script
  src="https://widget.ohallo.eu/embed.js"
  data-widget-id="wgt_abc123"
  data-position="bottom-left"
  data-primary-color="#1A1A2E"
  data-text-color="#E0E0E0"
  data-greeting="Search our help centre or send us a message."
  async
></script>

Widgets use public key authentication. The data-widget-id identifies the widget and its associated workspace. No API key is needed in the embed code — the widget ID is safe to include in client-side code.

The widget endpoint validates the widget ID server-side and only returns KB entries, accepts form submissions, or shows booking availability for the configured workspace. There is no way for a visitor to access data from other workspaces or tenants through the widget.

Rate limiting

Widget requests are rate-limited per IP address to prevent abuse. The default limits are generous enough for normal usage. If you expect very high traffic, contact support to adjust the limits for your widget.

Contact Form submissions

When a visitor submits the Contact Form widget, oHallo creates a new conversation:

Channel: The submission arrives as a widget channel conversation.
Contact: oHallo creates or matches a contact based on the email address provided.
Workspace: The conversation is routed to the workspace configured for the widget.
Processing: The conversation goes through the same agent pipeline as any other inbound message — planning, specialist agents, knowledge lookup, and response drafting.

You can view widget submissions alongside your email and chat conversations in the oHallo dashboard.

Booking submissions

When a visitor completes the booking widget, the following sequence occurs:

The widget fetches its configuration from GET /public/{publicKey}/config, which returns the form fields, appearance settings, and calendar metadata.
The visitor fills in the contact fields and picks a date.
The widget fetches available slots from GET /public/{publicKey}/availability?date=YYYY-MM-DD&timezone=Europe/Amsterdam. This returns time slots calculated from the calendar’s working hours, minus existing events, minus buffer time.
The visitor selects a time slot and submits.
POST /public/{publicKey}/submit with { fields, selectedSlot, sourceUrl } creates the booking.
oHallo creates a new conversation and a tentative event on your connected calendar.
The visitor receives a confirmation email with a link. The tentative slot is held for the configured expiry period (default: 24 hours).
When the visitor clicks the confirmation link, the calendar event is updated to confirmed and a conferencing link (Google Meet or Microsoft Teams) is generated.
Both the visitor and your team member receive confirmation emails with the meeting details and conferencing link.

If the visitor does not confirm within the expiry period, the tentative event is removed from the calendar and the slot becomes available again.

Complete example

Here is a full HTML page with a Knowledge Base widget embedded:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Acme Corp - Support</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      max-width: 800px;
      margin: 0 auto;
      padding: 40px 20px;
      color: #333;
    }
    h1 { margin-bottom: 8px; }
    p { line-height: 1.6; }
    .help-note {
      background: #f0f4ff;
      border-left: 4px solid #0F62FE;
      padding: 16px;
      margin: 24px 0;
    }
  </style>
</head>
<body>
  <h1>Acme Corp Support</h1>
  <p>Find answers to common questions or reach out to our team.</p>

  <div class="help-note">
    <p>Looking for a quick answer? Click the help button in the bottom-right corner to search our knowledge base.</p>
  </div>

  <h2>Contact us</h2>
  <p>
    If you cannot find what you are looking for, use the widget to send us a message.
    Our team typically responds within 4 business hours.
  </p>

  <!-- oHallo Knowledge Base Widget -->
  <script
    src="https://widget.ohallo.eu/embed.js"
    data-widget-id="wgt_abc123"
    data-position="bottom-right"
    data-primary-color="#0F62FE"
    data-greeting="Search our help centre or ask a question."
    async
  ></script>
</body>
</html>

Next steps

Managing the Knowledge Base — populate your KB with entries that the widget can search
Calendars — set up a calendar connection for booking widgets
Quickstart — get started with the oHallo API
What is MCP? — connect agents to your business systems

Embedding Widgets

Widget types

Knowledge Base widget

Contact Form widget

Booking widget

Creating a widget