thesquare-chat-widget

TheSquareAI accommodation booking chat widget for React / Next.js.

Connects to your /enquiry/chat backend and handles the full booking conversation flow — T1 welcome → T2 follow-up → T3 confirmation card → T4 enquiry received — out of the box.

Install

npm install thesquare-chat-widget

Usage

Minimal

import { ChatWidget } from 'thesquare-chat-widget';

<ChatWidget apiUrl="https://your-backend.com/enquiry/chat" />

With booker info

import { ChatWidget } from 'thesquare-chat-widget';

<ChatWidget
  apiUrl="https://your-backend.com/enquiry/chat"
  bookerInfo={{
    booker_name:           session.user.name,
    booker_email:          session.user.email,
    booker_contact_number: session.user.phone,
  }}
/>

Booker details are passed as props — they always appear on the booking summary card regardless of what the bot collects during conversation.

Full config

import { ChatWidget } from 'thesquare-chat-widget';

<ChatWidget
  apiUrl="https://your-backend.com/enquiry/chat"
  bookerInfo={{
    booker_name:           'Jane Doe',
    booker_email:          '[email protected]',
    booker_contact_number: '+44 7700 900123',
  }}
  title="TheSquareAI"
  subtitle="Accommodation Assistant · Online"
  position="bottom-right"
  accentColor="#E8344E"
  defaultOpen={false}
/>

Next.js

Wrap in a 'use client' component since the widget uses React state:

'use client';
import { ChatWidget } from 'thesquare-chat-widget';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <ChatWidget apiUrl="https://your-backend.com/enquiry/chat" />
    </>
  );
}

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | apiUrl | string | Yes | — | Your /enquiry/chat backend URL. | | bookerInfo | { booker_name?, booker_email?, booker_contact_number? } | No | — | Booker details shown on the booking summary card. | | title | string | No | "TheSquareAI" | Widget header title. | | subtitle | string | No | "Accommodation Assistant · Online" | Widget header subtitle. | | position | "bottom-right" \| "bottom-left" | No | "bottom-right" | FAB & panel position. | | accentColor | string (hex) | No | "#E8344E" | Primary brand colour. | | defaultOpen | boolean | No | false | Open the widget on mount. |

Chat flow

| Template | Triggered when | Renders | |----------|---------------|---------| | T1 | Widget opens | Greeting + list of required fields | | T2 | Some fields collected | Acknowledgement + remaining missing fields | | T3 | All fields collected | Booking summary card + Confirm / Edit buttons | | T4 | User confirms | Reference number + next steps + property results |

After T4, the widget collects optional guest details (name, email, phone + country code) and preferences (amenities, pet, parking, accessibility, special note). If the user skips everything, the session ends silently with no API call.

Expected API shape

Request

{
  "session_id": "abc-123",
  "message": "user input here",
  "user_profile": {
    "name": "Jane",
    "email": "[email protected]",
    "phone": "+44...",
    "phone_country_code": "+44",
    "is_guest": true
  }
}

session_id and user_profile are only sent when available. user_profile is populated from bookerInfo on the initial welcome call.

Response

{
  "session_id": "abc-123",
  "template": "T1",
  "follow_up_needed": true,
  "data": { ... }
}

CSS isolation

The widget is fully isolated — host app styles do not affect the widget and the widget does not leak styles into the host app. All styles are scoped to .sq-panel and use an explicit system font stack.

TypeScript

Types are included — no @types/ package needed.

import type { ChatWidgetProps, BookerInfo } from 'thesquare-chat-widget';

Publishing a new version

cd packages/chat-widget
# bump version in package.json, then:
npm run build
npm publish