` with a trigger doesn't. - **Without the floating button.** Triggers work even with `data-launcher="false"`. The panel opens when a trigger is clicked. ## Doing the same from code Each attribute has a [JavaScript API](https://justagoodguy.us/docs/javascript-api) twin: ```js GoodGuy.open('callback'); GoodGuy.book({ service: 'Haircut' }); GoodGuy.ask('Do you take walk-ins?'); ``` --- # JavaScript API > Control the widget from your own code with window.GoodGuy, and react to bookings and messages. Source: https://justagoodguy.us/docs/javascript-api ## Calling it before the script loads The widget loads with `async`, so your code may run first. Paste this queue stub before your own calls. Anything you call early is queued and run, in order, as soon as the widget is ready. ```html ``` In the queued form you pass the method name first: `GoodGuy('book', { service: 'Haircut' })`. Once the widget has loaded, `GoodGuy` also has every method on it, so `GoodGuy.book({ service: 'Haircut' })` works too. ## Methods | Method | What it does | |---|---| | `GoodGuy.open(view?, opts?)` | Opens the floating panel. `view` is `'chat'`, `'booking'`, `'callback'` or `'contact'`; without it, the last view is used. For booking, `opts` can be `{ service, staff }`. | | `GoodGuy.close()` | Closes the panel. | | `GoodGuy.toggle(view?)` | Opens or closes the panel. | | `GoodGuy.ask(text)` | Opens chat and sends `text` as the visitor's message. | | `GoodGuy.book({ service?, staff? })` | Opens booking from the start, with a service (id or name) and person (staff id) selected if you pass them. | | `GoodGuy.identify({ name?, phone?, email? })` | Prefills the visitor's details in forms and chat. Nothing is sent until the visitor submits something themselves. | | `GoodGuy.mount(element, type, options?)` | Renders an [inline widget](https://justagoodguy.us/docs/widgets) into `element`. | | `GoodGuy.on(event, callback)` | Subscribes to an [event](#events). | | `GoodGuy.off(event, callback)` | Unsubscribes. Pass the same function you passed to `on`. | | `GoodGuy.config` | The settings loaded from [`/api/public/config`](https://justagoodguy.us/docs/public-api#config), or `null` until they arrive. | | `GoodGuy.version` | The widget version. | ### identify Use `identify` when your visitor is already signed in to your own site, so they don't type their details twice: ```js GoodGuy('identify', { name: 'Dana Ruiz', phone: '+15555550123', email: 'dana@example.com' }); ``` Only `name`, `phone` and `email` are used, and empty values are ignored. Calling it again merges with what you passed before. ### mount ```js const el = document.querySelector('#book-here'); GoodGuy.mount(el, 'booking', { service: 'Haircut' }); ``` `options` uses the same settings as the `data-gg-*` attributes, without the prefix: | Option | Used by | |---|---| | `service` | `booking`, `contact` | | `staff` | `booking` | | `source` | `booking` (`'widget'` or `'booking_page'`) | | `height` | `chat` | | `token` | `manage`, `offer` | An element is only mounted once. An unknown type logs a warning and does nothing. ## Events ```js GoodGuy('on', 'booking.created', (booking) => { console.log('Booked', booking.serviceName, booking.whenLabel); }); ``` | Event | When | What the callback gets | |---|---|---| | `ready` | Settings have loaded | The config object. If you subscribe after it fired, your callback still runs once. | | `open` | The panel opens | `{ view }` | | `close` | The panel closes | nothing | | `message` | A chat message is sent or arrives | `{ role, content }`, where `role` is `'user'`, `'assistant'` or `'owner'` (a person from the business replying). Assistant messages also carry `cards`. | | `booking.created` | A booking was made, from the booking flow or the chat | Booking details: `id`, `status`, `serviceName`, `staffName`, `whenLabel`, `manageUrl` and `source`. From chat you also get `start` (ms since 1970). | | `callback.created` | A call-back was requested | `{ id, windowLabel, source }` | | `lead.created` | A message or quote request was sent | `{ id, source }` | `source` is `'widget'` or `'booking_page'` for the booking flow and forms, and `'chat'` when the AI did it. > [!NOTE] > A `booking.created` event can carry a `status` other than `confirmed`: `pending_approval` means you approve each booking first. See [booking statuses](https://justagoodguy.us/docs/rest-api#booking-statuses). ### Example: send bookings to your analytics ```js GoodGuy('on', 'booking.created', (b) => { if (typeof gtag === 'function') { gtag('event', 'booking', { service: b.serviceName, status: b.status, source: b.source }); } }); ``` Events only run in the visitor's browser. To record bookings reliably on your server, use [webhooks](https://justagoodguy.us/docs/webhooks). ## Errors Problems are logged to the console with a `[GoodGuy]` prefix, for example an unknown method name or widget type. The one exception is `mount`, which throws if you don't pass it an element. An error inside your own event callback is caught and logged so it can't break the widget. --- # Styling the widget > Match the widget to your brand with a colour, corner radius and font, without fighting your site's CSS. Source: https://justagoodguy.us/docs/styling ## Your site's CSS can't reach it Every part of the widget renders inside a shadow root (`attachShadow({ mode: 'open' })`), and resets itself with `:host { all: initial }`. Your stylesheet won't change it by accident, and its styles won't leak into your page. You style it on purpose with three CSS custom properties. Custom properties are inherited through the shadow boundary, so set them on `:root` or on the element that holds an inline widget. | Property | Default | What it changes | |---|---|---| | `--gg-color` | your dashboard colour | Brand colour for buttons, links and the floating button | | `--gg-radius` | `18px` | Corner radius of the panel and cards. Smaller parts scale from it. | | `--gg-font` | Figtree | Font family for all widget text | ```css :root { --gg-color: #0f766e; --gg-radius: 10px; --gg-font: 'Inter', system-ui, sans-serif; } /* Just this inline widget */ #book-here { --gg-radius: 4px; } ``` Set these in your stylesheet, so they're in place before the widget draws. The colour is read when each widget appears. ## Brand colour The colour comes from the first of these that's set: 1. `--gg-color` on the widget's element (or inherited from `:root`) 2. `data-color="#RRGGBB"` on the script tag 3. the colour in your dashboard's widget settings Any colour works. The widget works out readable shades for you: button labels switch between white and dark text, and links and focus rings are darkened or lightened until they pass WCAG AA contrast, in both light and dark mode. ## Fonts By default the widget adds one `` to your page's `` that loads Figtree from Google Fonts. Fonts have to load in the page itself, because `@font-face` rules don't register inside a shadow root. If Figtree is already loaded on the page, it isn't added again. To use your site's font instead, add `data-font="inherit"` to the script tag. The widget then uses the font of the element it sits in, and loads nothing from Google: ```html ``` You can still set `--gg-font` to pick a specific family. Make sure that font is loaded on your page. ## Position and the floating button - The button sits 16px from the bottom corner, above the phone's home bar on iPhones. - Choose the side in your dashboard's widget settings, or override it with `data-position="left"` or `"right"` on the script tag. - The button's label comes from the dashboard. The default is "Book or ask a question". - To hide the button and only use inline widgets and [triggers](https://justagoodguy.us/docs/triggers), add `data-launcher="false"`. ## Phones Under 520px wide, the panel opens full screen and keeps clear of notches and the home bar with `env(safe-area-inset-*)` padding. Browsers only report those insets when the page's viewport tag includes `viewport-fit=cover`: ```html ``` ## Dark mode The widget follows the visitor's `prefers-color-scheme` setting. In dark mode it uses dark surfaces but keeps your brand colour, adjusted so text on it stays readable. It does not read your site's own dark-mode switch. ## z-index The floating panel and button sit at `z-index: 2147483000`. If your own sticky header or cookie banner needs to sit above it, give that a higher value. --- # Hosted booking page and QR code > Every business gets a ready-made booking page and a QR code that points to it. No website needed. Source: https://justagoodguy.us/docs/booking-page ## Your booking page Your booking page lives at: ```text https://justagoodguy.us/b/your-business-name ``` The last part is made from your business name when you sign up (for example "Joe's Plumbing" becomes `joes-plumbing`). You'll find the exact link in the dashboard. The page shows: - your business name, and your town or city if you've added an address - a **Call** button with your number, if you have one - the [booking flow](https://justagoodguy.us/docs/widgets#booking): service, person, day and time, details, confirm - the AI chat underneath, for questions - your brand colour from the widget settings Bookings made here are marked as coming from your booking page, so you can tell them apart in your numbers. ## Where to share it - Your Instagram or Facebook bio - The booking link in your Google Business Profile - Your email signature and invoices - A "Book now" button on a website that can't run the widget (see [GoDaddy and other builders](https://justagoodguy.us/docs/add-widget#godaddy-and-other-builders)) The system also uses it for you: - [missed-call texts](https://justagoodguy.us/docs/phone#missed-call-text-back) link to it - cancellation messages include a "Book again" link to it - "pick a new time" texts link to it ## QR code Your QR code is an image at: ```text https://justagoodguy.us/b/your-business-name/qr.svg ``` It's black on white and points to your booking page. Because it's an SVG it stays sharp at any size, so you can print it on a counter sign, a business card, a van or a flyer. Open the link, save the image, and send it to your printer. > [!TIP] > Print a test copy and scan it with your phone before you print a hundred. Keep a white border around the code; scanners need it. ## Links your customers get ### Change or cancel: `/m/...` Every confirmation text and email has a private **Change or cancel** link. It opens a page where the customer can: - see their booking - pick a new time from open times in the next 14 days - cancel No login is needed, so the link works like a key. If a customer forwards it, whoever has it can change the booking. If a link stops working ("That link isn't valid any more"), the customer should contact you. ### Waitlist offers: `/offer/...` When you offer a freed-up time to your waitlist, each person gets a link. The first to tap **Claim this spot** gets it, and everyone else goes back on the waitlist. See [Waitlist](https://justagoodguy.us/docs/bookings#waitlist). --- # Public API > The browser-safe endpoints the widget uses, so you can build your own booking or chat interface. Source: https://justagoodguy.us/docs/public-api ## When to use it The public API is what the [widget](https://justagoodguy.us/docs/widgets) calls. Use it directly if you want to build your own booking form or chat window in the browser. For anything on your server, use the [REST API](https://justagoodguy.us/docs/rest-api) with a secret key instead. | | | |---|---| | Base URL | `https://justagoodguy.us/api/public` | | Auth | Your publishable key in the `X-GG-Key` header (or a `key` query parameter) | | CORS | Open to any origin, for `GET`, `POST` and `OPTIONS`. No cookies. | | Errors | `{ "error": "message" }` with a real status, the same as the [REST API](https://justagoodguy.us/docs/rest-api#errors) | If you've set [allowed sites](https://justagoodguy.us/docs/add-widget#allowed-sites), browser requests from other sites get `403`. > [!IMPORTANT] > Times in the public API are **milliseconds since 1970 (UTC)**, as numbers, not ISO strings. The REST API uses ISO strings. ## Rate limits Limits are per visitor IP address, to keep bots from filling your calendar: | Endpoint | Limit | |---|---| | `POST /events` | 300 per 10 minutes | | `GET /slots` | 120 per 10 minutes | | `POST /bookings` | 10 per hour | | `POST /callbacks` | 6 per hour | | `POST /leads` | 6 per hour | | `POST /chat` | 40 per 10 minutes, and 150 per visitor token per day | | `/api/manage/...` | 60 per 10 minutes | Over the limit you get `429` with a friendly message and `Retry-After: 60`. ## Config `GET /config` returns everything the widget needs to draw itself. ```bash curl https://justagoodguy.us/api/public/config -H "X-GG-Key: pk_your_key" ``` ```json { "business": { "name": "Joe's Plumbing", "slug": "joes-plumbing", "phone": "+15555550100", "timezone": "America/Chicago", "bookingPageUrl": "https://justagoodguy.us/b/joes-plumbing" }, "widget": { "color": "#3346D3", "position": "right", "label": "Book or ask a question", "showOnMobile": true }, "assistantName": "Assistant", "greeting": "Hi! I’m Joe's Plumbing’s assistant. I can answer questions or book you in.", "ai": true, "openNow": true, "callNow": false, "allowPickStaff": true, "turnstileSiteKey": null, "siteId": null, "practiceAi": false, "hours": { "booking": [{ "weekday": 1, "label": "Monday", "ranges": [{ "startMin": 480, "endMin": 1020, "label": "8:00 AM – 5:00 PM" }] }], "calls": [] }, "address": "12 Main St, Springfield, IL, 62701" } ``` - `ai` is `false` when the AI is paused or unavailable. Chat still answers with a fallback message. - `callNow` is `true` when someone can take a live call right now. - `hours` lists weekdays 1 (Monday) to 7 (Sunday). Times are minutes after local midnight. - `siteId` is set when the request comes from one of your hosted sites. - `practiceAi` is `true` when the server answers chat with its built-in practice AI instead of a real model (no AI key set up, or practice mode forced on). ## Services `GET /services` ```json { "services": [ { "id": "svc_2n4p6r8t0v1x3z5b", "name": "Drain cleaning", "description": null, "kind": "visit", "durationMin": 60, "priceLabel": "From $120", "staff": [{ "id": "stf_9h7f5d3b1z0x8v6t", "name": "Joe" }] } ] } ``` `staff` is empty when the business doesn't let customers pick a person. ## Slots `GET /slots?serviceId=...&staffId=...&from=...&days=...` | Query | Required | Notes | |---|---|---| | `serviceId` | yes | | | `staffId` | no | | | `from` | no | Milliseconds. Default now. | | `days` | no | Default 7, at most 21 | ```json { "timezone": "America/Chicago", "days": [ { "date": "2026-11-03", "label": "Tuesday, Nov 3", "slots": [{ "start": 1793718000000, "staffIds": ["stf_9h7f5d3b1z0x8v6t"], "label": "9:00 AM" }] } ] } ``` For classes, each slot also has `sessionId` and `seatsLeft`. ## Bookings `POST /bookings` ```json { "serviceId": "svc_2n4p6r8t0v1x3z5b", "staffId": "stf_9h7f5d3b1z0x8v6t", "start": 1793718000000, "sessionId": null, "customer": { "name": "Sam Lee", "phone": "+15555550123", "email": "" }, "notes": "Side gate is open", "address": { "line1": "12 Oak Ave", "postal": "62704" }, "source": "widget" } ``` - `customer` needs a `name` and a phone or email. - `address.line1` is required for visit services. If the service has a service area and the `postal` code isn't in it, you get `400`. - `sessionId` comes from the slot, for classes. - `source` is `widget` (default) or `booking_page`. Returns `201`: ```json { "booking": { "id": "bkg_8f3k2m9q1x7w4r6t", "status": "confirmed", "whenLabel": "Tuesday, Nov 3 at 9:00 AM", "serviceName": "Drain cleaning", "staffName": "Joe", "manageUrl": "https://justagoodguy.us/m/…" } } ``` `status` is `confirmed`, or `pending_approval` when the business approves each booking first. ## Call-backs `GET /callback-windows` returns the next open call-back windows (up to 10, in the next 7 days): ```json { "callNow": false, "windows": [{ "start": 1793725200000, "end": 1793732400000, "label": "Tuesday, Nov 3 at 11:00 AM – 1:00 PM" }] } ``` `POST /callbacks` with `{ "name", "phone", "reason"?, "windowStart"? }` returns `201`: ```json { "callback": { "id": "cbk_3j5l7n9q1s3u5w7y", "windowLabel": "Tuesday, Nov 3 at 11:00 AM – 1:00 PM" } } ``` Pick `windowStart` from a window, or leave it out for the next one. A call-back covers up to two hours. ## Messages and quote requests `POST /leads` with `{ "name", "phone"?, "email"?, "details", "serviceId"?, "subject"?, "pageUrl"?, "fields"?, "source"? }` returns `201` with `{ "lead": { "id" }, "emailed": true | false }`. A phone or email is required, and `details` up to 3,000 characters. `fields` holds any other form fields (`{ "Budget": "$500" }`), and `source` is `"widget"` (default) or `"site_form"` for a contact form on the business's own site. `emailed` is `true` only when a copy of the message (or the receptionist's answer) really went to their email. Only tell people "check your email" when it is. ## Analytics events `POST /events` counts visits and widget opens. It accepts a `text/plain` body so it works with `navigator.sendBeacon`, and the key goes inside the body: ```js navigator.sendBeacon('https://justagoodguy.us/api/public/events', JSON.stringify({ key: 'pk_your_key', type: 'page_view', url: location.href, referrer: document.referrer })); ``` `type` is `page_view`, `widget_open` or `widget_ping`. It returns `204`. Only the page's path is kept, not its query string. Visitors are counted with a hash that changes every day, and nothing is stored in the browser. `page_view` and `widget_ping` from your own site are also what makes the dashboard's install check pass. ## Chat ### Sending a message `POST /chat` streams the receptionist's reply as [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events). `EventSource` only does `GET`, so read the stream with `fetch`. | Field | Required | Notes | |---|---|---| | `message` | yes | Up to 1,500 characters | | `visitorToken` | yes | 16 to 64 random URL-safe characters you generate and keep for this visitor | | `conversationId` | no | From the `start` event of an earlier reply. Leave it out to start a new conversation. | | `page` | no | The page the visitor is on | | `selection` | no | `{ serviceId, start, staffId?, sessionId? }` when the visitor tapped a time in a slots card | ### Events in the stream Each event has a name and a `data` line of JSON with a matching `type`: ```sse event: start data: {"type":"start","conversationId":"cnv_5b7d9f1h3k5m7p9r","messageId":""} event: status data: {"type":"status","text":"Checking open times…"} event: delta data: {"type":"delta","text":"Here are the next open times"} event: card data: {"type":"card","card":{"type":"slots","serviceId":"svc_2n4p6r8t0v1x3z5b","serviceName":"Haircut","staffId":null,"timezone":"America/New_York","days":[]}} event: done data: {"type":"done","messageId":"msg_0a2c4e6g8j0l2n4q"} ``` | Event | Data | What to do | |---|---|---| | `start` | `conversationId` | Save it and send it with the next message | | `delta` | `text` | Append to the assistant's reply | | `status` | `text` | Show a short "working on it" line, like "Booking…" | | `card` | `card` | Render a card (see below) | | `replace` | `text` | Replace the whole reply text so far with this. Sent when a reply had to be corrected. | | `done` | `messageId` | The reply is finished | | `error` | `error` | Show the message. The stream ends. | | `ping` | `{}` | Keep-alive every 15 seconds. Ignore it. | Errors before the stream starts (a bad key, a missing field, a rate limit) come back as normal JSON errors with a status code, not as events. If a person from the business has taken the conversation over, the reply is just `start`, a `status` of "Sent to the team", and `done`. Their answer arrives on the [live stream](#live-replies-from-the-team). ### Cards | `card.type` | Fields | |---|---| | `slots` | `serviceId`, `serviceName`, `staffId`, `timezone`, `days[]` of `{ date, label, slots[] }`; each slot has `start`, `label`, `staffIds`, and `sessionId` for classes | | `services` | `items[]` of `{ id, name, durationMin, priceLabel, kind }` | | `booking` | `bookingId`, `status`, `serviceName`, `staffName`, `start`, `end`, `timezone`, `whenLabel`, `manageUrl` | | `callback` | `callbackId`, `windowLabel` | | `lead` | `leadId`, `summary` | | `verify` | `channel` (`sms` or `email`), `destinationHint` (a masked phone or email) | | `handoff` | `message` | When the visitor taps a time in a `slots` card, send a normal message (the widget sends "9:00 AM on Tuesday, Nov 3 works for me") with `selection` set to that slot. That tells the receptionist exactly which time was picked. ### Reading the stream ```js async function chat({ message, visitorToken, conversationId }, onEvent) { const res = await fetch('https://justagoodguy.us/api/public/chat', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-GG-Key': 'pk_your_key' }, body: JSON.stringify({ message, visitorToken, conversationId }), }); if (!res.ok) throw new Error((await res.json()).error); const reader = res.body.pipeThrough(new TextDecoderStream()).getReader(); let buffer = ''; for (;;) { const { value, done } = await reader.read(); if (done) break; buffer += value; let end; while ((end = buffer.indexOf('\n\n')) >= 0) { const block = buffer.slice(0, end); buffer = buffer.slice(end + 2); const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('\n'); if (!data) continue; const event = JSON.parse(data); if (event.type !== undefined) onEvent(event); } } } ``` A conversation can run for 80 messages, after which the visitor is asked to start a new chat or call. ### History `GET /conversation?conversationId=...&visitorToken=...` returns the last 50 messages, so you can redraw the chat after a reload: ```json { "conversationId": "cnv_5b7d9f1h3k5m7p9r", "humanTakeover": false, "messages": [ { "id": "msg_…", "role": "user", "content": "Do you have anything Saturday?", "cards": [], "createdAt": 1793700000000 }, { "id": "msg_…", "role": "assistant", "content": "Saturday has a few times open.", "cards": [{ "type": "slots", "...": "..." }], "createdAt": 1793700002000 } ] } ``` `role` is `user`, `assistant` or `owner`. The `visitorToken` must match the one that started the conversation. ### Live replies from the team `GET /conversation/stream?conversationId=...&visitorToken=...&key=pk_...` is a normal `EventSource` stream. When someone from the business replies in their Inbox, you get: ```sse event: message data: {"id":"msg_…","role":"owner","content":"Hi Sam, yes we can fit you in at 10.","author":"Joe"} ``` It also sends `ready` when it opens and `ping` every 20 seconds. ## Manage links and offers These use the token from the customer's link instead of a key. | Request | What it does | |---|---| | `GET /api/manage/:token` | The booking, the business, and whether it can still be changed (`canChange`) | | `GET /api/manage/:token/slots?from=` | Open times for the next 14 days, for moving it | | `POST /api/manage/:token/reschedule` | `{ "start": ms }` | | `POST /api/manage/:token/cancel` | `{ "reason"? }`. Returns `{ ok: true }`. | | `GET /api/offer/:token` | A waitlist offer: `serviceName`, `whenLabel`, `available`, `claimed` | | `POST /api/offer/:token/claim` | Claims it. `409` if someone else got it first; `410` if it expired. | --- # REST API > Read and create bookings, check availability and look up customers from your own server, with a secret key. Source: https://justagoodguy.us/docs/rest-api ## Overview | | | |---|---| | Base URL | `https://justagoodguy.us/api/v1` | | Auth | `Authorization: Bearer sk_...` | | Format | JSON in, JSON out. Send `Content-Type: application/json` with every body. | | Times | ISO 8601. Responses use UTC, like `2026-11-03T19:00:00.000Z`. | | Rate limit | 600 requests per minute per key | | Machine-readable spec | [`/api/openapi.json`](https://justagoodguy.us/api/openapi.json), browsable in the [API reference](https://justagoodguy.us/docs/api-reference) | The OpenAPI document is generated from the same schemas the server uses to check requests, so it always matches what the server accepts. ## Authentication Create a secret key in **More → Developers** (only the business owner can). It starts with `sk_` and is shown **once**, so copy it somewhere safe. We only keep a fingerprint of it. ```bash curl https://justagoodguy.us/api/v1/services \ -H "Authorization: Bearer sk_your_secret_key" ``` - Secret keys can read and change your bookings and customers. Keep them on your server. Never put one in a web page or an app. - For the browser, use your publishable key (`pk_...`) with the [widget](https://justagoodguy.us/docs/add-widget) or the [public API](https://justagoodguy.us/docs/public-api) instead. - Revoke a key in **More → Developers**. It stops working straight away. The dashboard also shows when each key was last used. ## Errors Errors always come back as JSON with a plain-English message and a real HTTP status: ```json { "error": "Sorry, that time was just taken or isn’t available. Please pick another time." } ``` | Status | Meaning | |---|---| | `400` | Something in the request is missing or wrong. The message says what, for example `Please check the “service_id” field.` | | `401` | No key, not a secret key, or a revoked key | | `404` | That booking, customer or service doesn't exist in your business | | `409` | The time isn't available (taken, outside hours, too soon or too far ahead) | | `429` | Over the rate limit. Wait for the `Retry-After` header (60 seconds) and try again. | | `500` | Something broke on our side. It's safe to retry reads; check before retrying a booking. | The messages are written for people, so you can show them to your users as they are. ## Rate limits Each secret key can make 600 requests per minute. The count resets every minute. Requests over the limit get `429` with `{ "error": "Rate limit: 600 requests per minute." }` and a `Retry-After: 60` header. ## Booking statuses | `status` | Meaning | |---|---| | `pending_approval` | Waiting for the business to approve it | | `confirmed` | Booked | | `completed` | The business marked it done | | `cancelled` | Cancelled by the customer, the business or the API | | `no_show` | The customer didn't turn up | `source` says where the booking came from: `web_chat`, `widget`, `booking_page`, `phone`, `sms`, `dashboard`, `assistant` or `api`. ## The Booking object ```json { "id": "bkg_8f3k2m9q1x7w4r6t", "status": "confirmed", "source": "api", "start": "2026-11-03T19:00:00.000Z", "end": "2026-11-03T19:45:00.000Z", "timezone": "America/New_York", "service": { "id": "svc_2n4p6r8t0v1x3z5b", "name": "Haircut" }, "staff": { "id": "stf_9h7f5d3b1z0x8v6t", "name": "Dana" }, "customer": { "id": "cus_4k6m8p0r2t4v6x8z", "name": "Sam Lee", "phone": "+15555550123", "email": null }, "priceCents": 4500, "notes": null } ``` `staff` is `null` when no person is attached. Money is in cents of the business's currency. `priceCents` is `null` when the service has no set price. ## Services and team ### List services `GET /v1/services` returns your active services. ```bash curl https://justagoodguy.us/api/v1/services -H "Authorization: Bearer $JAGG_KEY" ``` ```json { "data": [ { "id": "svc_2n4p6r8t0v1x3z5b", "name": "Haircut", "kind": "appointment", "durationMin": 45, "priceCents": 4500, "description": null } ] } ``` `kind` is `appointment`, `visit`, `class` or `quote`. See [service kinds](https://justagoodguy.us/docs/bookings#service-kinds). ### List team members `GET /v1/staff` returns your active team members. ```bash curl https://justagoodguy.us/api/v1/staff -H "Authorization: Bearer $JAGG_KEY" ``` ```json { "data": [{ "id": "stf_9h7f5d3b1z0x8v6t", "name": "Dana", "color": "#2563eb" }] } ``` ## Availability ### Open times for a service `GET /v1/availability` | Query | Required | Notes | |---|---|---| | `service_id` | yes | | | `staff_id` | no | Only this person's times. Without it, a time is open if anyone who does the service is free. | | `from` | no | ISO date-time to start from. Defaults to now. Times in the past are never returned. | | `days` | no | How many days to look ahead, 1 to 31. Default 7. | ```bash curl "https://justagoodguy.us/api/v1/availability?service_id=svc_2n4p6r8t0v1x3z5b&days=3" \ -H "Authorization: Bearer $JAGG_KEY" ``` ```json { "timezone": "America/New_York", "data": [ { "date": "2026-11-03", "label": "Tuesday, Nov 3", "slots": [ { "start": "2026-11-03T19:00:00.000Z", "label": "2:00 PM", "staffIds": ["stf_9h7f5d3b1z0x8v6t"] } ] } ] } ``` Days are grouped by the business's local date, and `label` is ready to show. Days with no open times are left out. The business's minimum notice and how-far-ahead rules apply, and quote-type services never have open times. ## Bookings ### List bookings `GET /v1/bookings` | Query | Notes | |---|---| | `from` | ISO date-time. Default: 24 hours ago. | | `to` | ISO date-time. Default: 30 days after `from`. | | `status` | Comma-separated statuses, for example `confirmed,pending_approval`. Default: all. | Returns bookings that overlap the range, oldest first. ```bash curl "https://justagoodguy.us/api/v1/bookings?from=2026-11-01T00:00:00Z&to=2026-11-08T00:00:00Z&status=confirmed" \ -H "Authorization: Bearer $JAGG_KEY" ``` ```json { "data": [ { "id": "bkg_8f3k2m9q1x7w4r6t", "status": "confirmed", "...": "a Booking object" } ] } ``` ### Create a booking `POST /v1/bookings` | Field | Required | Notes | |---|---|---| | `service_id` | yes | | | `start` | yes | An exact `start` from [availability](#open-times-for-a-service). Send it back as you got it. | | `staff_id` | no | Book with this person. Without it, the booking goes to whoever is free with the fewest bookings that day. | | `customer.name` | yes | | | `customer.phone` or `customer.email` | one of them | Used to match an existing customer and to send the confirmation | | `notes` | no | Up to 1,000 characters, shown to the business | ```bash curl https://justagoodguy.us/api/v1/bookings \ -H "Authorization: Bearer $JAGG_KEY" \ -H "Content-Type: application/json" \ -d '{ "service_id": "svc_2n4p6r8t0v1x3z5b", "start": "2026-11-03T19:00:00.000Z", "customer": { "name": "Sam Lee", "phone": "+15555550123" }, "notes": "Booked through our members portal" }' ``` Returns `201` with the [Booking](#the-booking-object). What happens next is the same as for any other booking: - The customer is matched by phone or email, or added as a new customer. - They get a confirmation by text and email (or "Request received" if the business approves each booking). - The business gets a "New booking" alert, and the [`booking.created` webhook](https://justagoodguy.us/docs/webhooks#events) fires. - If the service needs approval, `status` is `pending_approval`. There are no idempotency keys. If a create request times out, [list bookings](#list-bookings) for that time before retrying. Retrying a booking that did go through usually fails with `409`, because the time is now taken. ### Get a booking `GET /v1/bookings/{id}` ```bash curl https://justagoodguy.us/api/v1/bookings/bkg_8f3k2m9q1x7w4r6t -H "Authorization: Bearer $JAGG_KEY" ``` ### Move a booking `POST /v1/bookings/{id}/reschedule` | Field | Required | Notes | |---|---|---| | `start` | yes | An exact open `start` from availability | | `staff_id` | no | Move to this person. Without it, the same person is kept if they're free, otherwise anyone free. | | `notify` | no | Text and email the customer about the change. Default `true`. | ```bash curl https://justagoodguy.us/api/v1/bookings/bkg_8f3k2m9q1x7w4r6t/reschedule \ -H "Authorization: Bearer $JAGG_KEY" \ -H "Content-Type: application/json" \ -d '{ "start": "2026-11-04T15:30:00.000Z" }' ``` Only `pending_approval` and `confirmed` bookings can be moved (others get `400`). Reminders are rescheduled for the new time, and the `booking.rescheduled` webhook fires. ### Cancel a booking `POST /v1/bookings/{id}/cancel` | Field | Required | Notes | |---|---|---| | `reason` | no | Saved on the booking | | `notify` | no | Tell the customer. Default `true`. | ```bash curl https://justagoodguy.us/api/v1/bookings/bkg_8f3k2m9q1x7w4r6t/cancel \ -H "Authorization: Bearer $JAGG_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "Customer called to cancel" }' ``` Cancelling an already-cancelled booking returns it unchanged. Pending reminders are stopped and the `booking.cancelled` webhook fires. ## Customers ### The Customer object ```json { "id": "cus_4k6m8p0r2t4v6x8z", "name": "Sam Lee", "phone": "+15555550123", "email": null, "visitCount": 3, "tags": ["regular"] } ``` ### List or search customers `GET /v1/customers` | Query | Notes | |---|---| | `q` | Part of a name, for example `sam` | | `limit` | 1 to 500. Default 100. | Most recently updated first. ```bash curl "https://justagoodguy.us/api/v1/customers?q=sam&limit=20" -H "Authorization: Bearer $JAGG_KEY" ``` ### Create or update a customer `POST /v1/customers` with `name` and a `phone` or `email`. If a customer with that phone or email exists, it's updated instead of duplicated: - a missing phone or email is filled in - an existing name is kept (a different spelling is saved as an alias) ```bash curl https://justagoodguy.us/api/v1/customers \ -H "Authorization: Bearer $JAGG_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Sam Lee", "phone": "+15555550123", "email": "sam@example.com" }' ``` Returns `201` with the Customer. Phone numbers are stored in international format (`+1...`); a 10-digit number is read as a US or Canadian number. ### Get a customer `GET /v1/customers/{id}` ```bash curl https://justagoodguy.us/api/v1/customers/cus_4k6m8p0r2t4v6x8z -H "Authorization: Bearer $JAGG_KEY" ``` ## Requests ### Open call-backs `GET /v1/callbacks` returns call-back requests that are still open. ```bash curl https://justagoodguy.us/api/v1/callbacks -H "Authorization: Bearer $JAGG_KEY" ``` ```json { "data": [ { "id": "cbk_3j5l7n9q1s3u5w7y", "customerId": "cus_4k6m8p0r2t4v6x8z", "windowStart": "2026-11-03T21:00:00.000Z", "windowEnd": "2026-11-03T23:00:00.000Z", "reason": "Quote for a new water heater", "status": "open" } ] } ``` ### Messages and quote requests `GET /v1/leads` returns messages and quote requests with status `new` or `contacted`. ```bash curl https://justagoodguy.us/api/v1/leads -H "Authorization: Bearer $JAGG_KEY" ``` ```json { "data": [ { "id": "led_6c8e0g2j4l6n8q0s", "customerId": "cus_4k6m8p0r2t4v6x8z", "kind": "quote", "details": "Leaking tap in the kitchen", "status": "new", "createdAt": "2026-11-02T14:12:00.000Z" } ] } ``` `kind` is `quote` (taken by the receptionist) or `message` (sent from a contact form). ## A complete example Find the next open time for a service and book it, in Node 18 or later: ```js const API = 'https://justagoodguy.us/api/v1'; const headers = { Authorization: `Bearer ${process.env.JAGG_KEY}`, 'Content-Type': 'application/json' }; async function call(path, init) { const res = await fetch(API + path, { headers, ...init }); const body = await res.json(); if (!res.ok) throw new Error(`${res.status}: ${body.error}`); return body; } const { data: services } = await call('/services'); const haircut = services.find((s) => s.name === 'Haircut'); const { data: days } = await call(`/availability?service_id=${haircut.id}&days=7`); const first = days[0]?.slots[0]; if (!first) throw new Error('Nothing open this week'); const booking = await call('/bookings', { method: 'POST', body: JSON.stringify({ service_id: haircut.id, start: first.start, customer: { name: 'Sam Lee', phone: '+15555550123' } }), }); console.log(booking.status, booking.start); ``` --- # Webhooks > Get a signed HTTPS request on your server whenever a booking, call-back or message comes in. Source: https://justagoodguy.us/docs/webhooks ## Set one up In **More → Developers**, add a webhook: - **URL.** Must start with `https://`. - **Events.** Pick the events you want, or `*` for all of them. You get a signing secret that starts with `whsec_`. It's shown in full **once**, so store it with your other secrets. You'll use it to [check the signature](#verify-the-signature) on every request. The same page shows your recent deliveries: the event, whether it was delivered, how many tries it took, and the status code your server sent back. Only the business owner can manage webhooks. ## Events | Event | Sent when | `data` | |---|---|---| | `booking.created` | A booking is made, from any channel. | a [Booking](https://justagoodguy.us/docs/rest-api#the-booking-object) | | `booking.rescheduled` | A booking moves to a new time | a Booking | | `booking.cancelled` | A booking is cancelled, or marked as a no-show | a Booking | | `callback.created` | Someone asks for a call-back through the receptionist (chat, phone or text) or the call-back form | see below | | `lead.created` | A message or quote request comes in through the receptionist or the contact form | see below | | `customer.created` | A new customer record was created (from a booking, chat, call, text or import). | `{ id, name, phone, email, source }` | | `conversation.closed` | You marked a conversation resolved in the Inbox. | `{ id, channel, outcomes, customerId }` | Bookings created in your dashboard send `booking.created` too, so your systems see every booking. ## What a request looks like ```http POST /your/webhook HTTP/1.1 Content-Type: application/json User-Agent: JustAGoodGuy-Webhooks/1 X-JAGG-Signature: t=1793732400,v1=<64 hex characters> ``` ```json { "id": "evt_1b3d5f7h9k1m3p5r", "type": "booking.created", "created": "2026-11-03T19:00:00.000Z", "data": { "id": "bkg_8f3k2m9q1x7w4r6t", "status": "confirmed", "source": "web_chat", "start": "2026-11-05T15:00:00.000Z", "end": "2026-11-05T15:45:00.000Z", "timezone": "America/New_York", "service": { "id": "svc_2n4p6r8t0v1x3z5b", "name": "Haircut" }, "staff": { "id": "stf_9h7f5d3b1z0x8v6t", "name": "Dana" }, "customer": { "id": "cus_4k6m8p0r2t4v6x8z", "name": "Sam Lee", "phone": "+15555550123", "email": null }, "priceCents": 4500, "notes": null } } ``` Every request has the same envelope: | Field | What it is | |---|---| | `id` | A unique event id. It stays the same when a delivery is retried, so use it to skip duplicates. | | `type` | The event name | | `created` | When the event happened | | `data` | The event's details | `callback.created` data: ```json { "id": "cbk_3j5l7n9q1s3u5w7y", "customer": { "name": "Sam Lee", "phone": "+15555550123" }, "windowStart": "2026-11-03T21:00:00.000Z", "windowEnd": "2026-11-03T23:00:00.000Z", "reason": "Quote for a new water heater" } ``` `lead.created` data: ```json { "id": "led_6c8e0g2j4l6n8q0s", "customer": { "name": "Sam Lee", "phone": "+15555550123", "email": null }, "details": "Leaking tap in the kitchen", "source": "site_form", "pageUrl": "https://example.com/contact" } ``` `source` is `site_form` for a contact form on the business's site and `widget` for the widget's message form. Requests the receptionist takes in a conversation have `details` only. ## Responding and retries - Answer with any `2xx` status within **10 seconds**. Do slow work after you've answered. - Anything else (another status, a timeout, a connection error) counts as a failure, and the delivery is tried again later. - Each delivery is tried up to **8 times**. The wait after each failed try doubles: 2, 4, 8, 16, 32, 64, then 128 minutes. After the 8th failure it's marked failed and not tried again. - Deliveries are sent within about 15 seconds of the event. - Events can arrive out of order, and occasionally more than once. Use `id` to skip duplicates, and the booking's own fields (not the order of arrival) to decide what's current. ## Verify the signature Every request has an `X-JAGG-Signature` header: ```text X-JAGG-Signature: t=,v1= ``` `v1` is the HMAC-SHA256 of the string `.`, keyed with your `whsec_` secret, in lowercase hex. To check it: 1. Read the **raw** request body, exactly as it arrived. Don't parse and re-serialise the JSON first; that changes the bytes. 2. Split the header on `,` and take `t` and `v1`. 3. Compute `HMAC-SHA256(secret, t + "." + body)` as hex. 4. Compare it with `v1` using a constant-time comparison. 5. Reject the request if `t` is more than a few minutes away from your clock, so an old request can't be replayed. The examples use 5 minutes. `t` is set again on each retry, so a retried delivery has a fresh timestamp and signature. ### Node ```js Node (Express) import crypto from 'node:crypto'; import express from 'express'; const SECRET = process.env.JAGG_WEBHOOK_SECRET; // whsec_... export function verifyJaggSignature(rawBody, header, secret, toleranceSec = 300) { if (!header) return false; const parts = Object.fromEntries( header.split(',').map((kv) => { const i = kv.indexOf('='); return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()]; }), ); const t = Number(parts.t); if (!Number.isInteger(t) || !parts.v1) return false; if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'); const a = Buffer.from(expected, 'utf8'); const b = Buffer.from(parts.v1, 'utf8'); return a.length === b.length && crypto.timingSafeEqual(a, b); } const app = express(); // express.raw keeps the body as bytes, so the signature can be checked. app.post('/webhooks/jagg', express.raw({ type: 'application/json' }), (req, res) => { const raw = req.body.toString('utf8'); if (!verifyJaggSignature(raw, req.get('X-JAGG-Signature'), SECRET)) return res.status(400).send('Bad signature'); const event = JSON.parse(raw); res.sendStatus(200); // answer first, then do the work if (event.type === 'booking.created') { console.log('New booking', event.data.id, event.data.start); } }); app.listen(3000); ``` ### Python ```python Python (Flask) import hashlib import hmac import json import os import time from flask import Flask, abort, request SECRET = os.environ["JAGG_WEBHOOK_SECRET"] # whsec_... def verify_jagg_signature(raw_body: bytes, header: str | None, secret: str, tolerance: int = 300) -> bool: if not header: return False parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p) try: t = int(parts["t"]) v1 = parts["v1"] except (KeyError, ValueError): return False if abs(time.time() - t) > tolerance: return False signed = f"{t}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, v1) app = Flask(__name__) @app.post("/webhooks/jagg") def jagg_webhook(): raw = request.get_data() # the raw bytes, before any JSON parsing if not verify_jagg_signature(raw, request.headers.get("X-JAGG-Signature"), SECRET): abort(400) event = json.loads(raw) if event["type"] == "booking.created": print("New booking", event["data"]["id"], event["data"]["start"]) return "", 200 ``` ### PHP ```php PHP $tolerance) return false; $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret); return hash_equals($expected, $parts['v1']); } $raw = file_get_contents('php://input'); // the raw body $header = $_SERVER['HTTP_X_JAGG_SIGNATURE'] ?? null; if (!verify_jagg_signature($raw, $header, $secret)) { http_response_code(400); exit('Bad signature'); } $event = json_decode($raw, true); if ($event['type'] === 'booking.created') { error_log('New booking ' . $event['data']['id']); } http_response_code(200); ``` ### Test vector Use this to check your code without a live request. With the secret `whsec_test_secret`, the timestamp `1793732400` and the body `{"id":"evt_test","type":"booking.created"}`, the signature is: ```text v1=cd83919399dd5fbe165dce8318ade93acc1f323e914fd435b0c1b2dcdab4c4e3 ``` Your function should accept it when you skip the timestamp check (the timestamp is in the past). ## Good practice - Check the signature before you trust anything in the body. - Answer fast, then do the work in a queue or background job. - Make your handler safe to run twice for the same `id`. - To get the latest state of a booking, call [`GET /v1/bookings/{id}`](https://justagoodguy.us/docs/rest-api#get-a-booking). - If your endpoint is down for a long time, deliveries give up after the 8th try. Use the [REST API](https://justagoodguy.us/docs/rest-api#list-bookings) to catch up. --- # Hosting your website > Upload your site, roll back with one tap, connect your own domain, or ask us to build it for you. Source: https://justagoodguy.us/docs/hosting ## Three ways to have a website - **Keep the site you have** and [add the widget](https://justagoodguy.us/docs/add-widget) to it. - **Let us host it.** Upload your site in the dashboard. It gets a free web address straight away, and you can connect your own domain. - **Ask us to build it.** Tell us what you want with [Build it for me](#build-it-for-me). You can also [run the host app on your own server](https://justagoodguy.us/docs/own-server) if you'd rather keep the files on a machine you control. Hosted sites get the widget added automatically. You can turn that off per site in **Dashboard → Website**. ## Upload your site In **Dashboard → Website**, drop in a `.zip` file or a folder with your site in it. What we need: - **A home page called `index.html` at the top.** If everything is inside one folder (which is what you get when you zip a folder), that's fine: we lift it up a level for you. If we can't find `index.html`, the upload stops and tells you so. - **Up to 150 MB zipped**, up to 400 MB once unzipped, and up to 5,000 files. What we leave out, so they never go live by mistake: - Mac and Windows clutter: `__MACOSX`, `.DS_Store`, `Thumbs.db` - `.git` folders and `.env` files A zip that tries to write outside its own folder is rejected. Big uploads go up in pieces, so a slow connection is fine. Your site goes live as soon as the upload finishes. ### Roll back Every upload is kept as a version. The dashboard lists your recent versions with their date, size and file count. Tap an older one to put it back live. The newer version isn't deleted, so you can switch back again. ### How many sites Your plan sets how many hosted sites you can have. If you reach the limit, the dashboard tells you. Message us if you need more. ## Build it for me Don't have a site, or don't want to touch one? Send a request from **Dashboard → Website**. You'll be asked for: - which pages you want (Home, About, Services and Contact to start with) - the look you're after, in your own words - what your business does - your current website, if you have one - the domain you'd like to use - logos and photos (PNG, JPG, WebP, GIF or SVG images, or PDFs, up to 15 MB each) - anything else we should know Your request goes through these stages, and you get an email each time it moves: | Stage | What it means | |---|---| | New | It's in the queue. | | In progress | We've started building. | | Review | Your new site is up on your hosted address for you to look over. | | Live | It's live. | | Cancelled | The request was closed. | You can send messages and files back and forth on the request at any time. ## Use your own domain Your hosted site starts on a free address. To use your own domain, like `joesplumbing.com`: 1. **Add the domain.** In **Dashboard → Website**, enter it without `www` or `https://`, for example `joesplumbing.com`. The dashboard then shows a **target** to point at. 2. **Point `www` at the target.** At the company where you bought the domain (your registrar or DNS host), add a **CNAME** record for `www` whose value is the target from the dashboard. 3. **Forward the bare domain.** Most registrars can't point the bare `joesplumbing.com` at a CNAME. Use the registrar's **forwarding** (or "redirect") feature to send `joesplumbing.com` to `https://www.joesplumbing.com`. 4. **Check it.** Back in the dashboard, tap the domain check. It shows what your DNS says right now for both names, and turns ready once `www` points at the target. Your DNS records end up looking like this (the target value is an example; use the one in your dashboard): | Type | Name | Value | |---|---|---| | CNAME | `www` | `joes-plumbing.example-target.net` | | Forward | `@` (the bare domain) | `https://www.joesplumbing.com` | - DNS changes usually show up within an hour, but can take up to a day. - The secure `https://` certificate is set up for you once the DNS change is live. - Each domain can be connected to one site only. If it's already connected elsewhere, the dashboard says so. > [!NOTE] > If your site runs on [your own server](https://justagoodguy.us/docs/own-server), point your domain at that server instead of the target. The host app page explains how. --- # Use your own server: the host app > Run the small host app on your own Linux server, drop site folders into it, and manage everything from your dashboard. Source: https://justagoodguy.us/docs/own-server ## What the host app does The host app is a small web server you run on your own machine. Once it's connected to your account it: - serves every site folder you put in its `sites/` folder - serves sites you upload in the dashboard, and switches versions when you roll back - adds your widget to every page, unless you turn that off - gets free HTTPS certificates for your domains (with the Docker setup) - shows up in **Dashboard → Website**, with whether it's online You don't need it if we host your site for you. It's for people who want the files on a machine they control. ## What you need - A Linux server running Ubuntu or Debian, with a login that can use `sudo`. A small cloud server works well. - Ports 80 and 443 open to the internet, for websites and HTTPS. - Your domain, if you have one. You can also start without it. ## Install 1. **Get a pairing code.** In your dashboard, go to **Website**, then **Use my own server**, then **Add a server**. You get a code like `ABCD-1234`. Codes work for 24 hours. 2. **Run the installer** on your server, with your code in it: ```bash curl -fsSL https://justagoodguy.us/downloads/host/install.sh | sudo bash -s -- --code ABCD-1234 ``` It installs Docker if needed, starts the host app behind [Caddy](https://caddyserver.com) for automatic HTTPS, and connects it to your account. At the end it prints the link to your **setup page**. Keep that link private. 3. **Point your domain at the server.** At your registrar, add an **A record** for `@` and for `www`, each with your server's IP address. 4. **Visit your domain.** The first visit can take a few seconds while the HTTPS certificate is set up. > [!WARNING] > Piping a script into `sudo bash` runs it as root. If you'd rather check it first, download it, read it, then run it. Everything lives in `/opt/goodguy`: your site folders in `/opt/goodguy/sites`, and the settings in `/opt/goodguy/.env`. ### Installer options Add these after `bash -s --`: | Option | What it does | |---|---| | `--code ABCD-1234` | Connect to your account straight away | | `--no-docker` | Run with Node.js 24 and systemd instead of Docker. This serves plain HTTP only, with no automatic HTTPS. | | `--port N` | Port for `--no-docker` (default 80) | | `--dir DIR` | Install folder (default `/opt/goodguy`) | | `--api URL` | The Just a Good Guy address to connect to (default `https://justagoodguy.us`) | | `--sites-domain NAME` | Also serve each folder at `.` | > [!NOTE] > The host app itself speaks plain HTTP. HTTPS comes from Caddy, which the Docker install sets up for you. With `--no-docker`, put your own web server in front if you need HTTPS, or use the Docker install. Caddy works well with the [ask endpoint](#https-with-caddy-the-ask-endpoint) below. ### Without the installer If you'd rather set it up by hand, the host app ships with a `Dockerfile`, a `docker-compose.yml` and a `Caddyfile`. Put them in one folder with the built `dist/host.mjs`, add a `.env` file with your settings (see [Settings](#settings)), and start it: ```bash docker compose up -d --build ``` ## Connect it to your account If you didn't pass `--code` to the installer, open the setup page link it printed. It looks like `http://YOUR-SERVER-IP/_gg/setup?token=...`. There you can connect in two ways: - **With a pairing code (easiest).** Type the code from **Website → Use my own server → Add a server**. - **By signing in.** Enter your Just a Good Guy email and password. Your password is used once, to get a connection key for this server, and is never saved on the server. Only a business owner can connect a server. The setup page also shows which business the server is connected to, which sites it serves and where each one comes from, when it last synced, and a button to disconnect it. Once it's connected, your dashboard shows the server as online. It checks in about once a minute, and counts as online if it was seen in the last 2 minutes. ### Lost the setup link? The setup page needs its setup token, so nobody else can connect your server to their own account. The installer creates the token for you. To see it: ```bash sudo grep SETUP_TOKEN /opt/goodguy/.env ``` Then open `http://YOUR-SERVER-IP/_gg/setup?token=` with the token on the end. Pages opened from the server itself don't need the token. ## Add your sites There are two ways, and you can mix them. **Upload it in the dashboard.** Go to **Website** and upload a zip of your site. The server shows the new version within seconds. For uploaded sites, turn the widget on or off in the dashboard. **Put a folder on the server.** Copy your site's folder into `/opt/goodguy/sites/`, for example with an SFTP app. Each folder needs an `index.html` at the top. ```text sites/ joesplumbing.com/ index.html about.html images/ spring-offer/ index.html ``` - **Name a folder after your domain** (`sites/joesplumbing.com`) and it becomes the site for that domain. `www.joesplumbing.com` is included. - **Any other name** (`sites/spring-offer`) becomes a site on a free address, if that name isn't already taken. - New folders are picked up within a few seconds, and appear in your dashboard after the next check-in. - If the server has only one site, it shows that site for every address, including the server's bare IP address. - Your sites keep working if the connection to Just a Good Guy drops. The server keeps the last version it received. ### Turning the widget off for one site The host app adds your widget to each page. To leave it out for one site, add a file called `.goodguy.json` to that site's folder: ```json { "injectWidget": false } ``` ## Settings With the installer, change settings in `/opt/goodguy/.env` (it holds `JAGG_API`, `SETUP_TOKEN` and `SITES_DOMAIN`), then restart: `cd /opt/goodguy && sudo docker compose up -d`. Running the host app yourself, set these as environment variables or command-line options. | Variable | Option | Default | What it does | |---|---|---|---| | `JAGG_API` | `--api` | `https://justagoodguy.us` | The Just a Good Guy server to connect to | | `HOST_PORT` | `--port` | `8200` | Port the host app listens on | | `HOST_BIND` | `--bind` | `0.0.0.0` | Address to listen on | | `SITES_DIR` | `--sites-dir` | `./sites` | Where your site folders live | | `STATE_DIR` | `--state-dir` | `./state` | Where it keeps its connection key and downloaded versions. Back this up. | | `SETUP_TOKEN` | `--setup-token` | none | Requires this secret to use the setup page | | `SITES_DOMAIN` | `--sites-domain` | none | Also serve `.`, for example `spring-offer.example.com` | Other commands: ```bash node host.mjs status # what it's connected to, and its sites node host.mjs setup-url # the setup page link, with its token node host.mjs disconnect # forget the connection on this server node host.mjs --help ``` With the Docker install, run them inside the container, for example `cd /opt/goodguy && sudo docker compose exec host node /app/host.mjs status`. Logs: `sudo docker compose logs -f host` (Docker) or `journalctl -u goodguy-host -f` (without Docker). ## For developers ### HTTPS with Caddy: the ask endpoint Caddy's on-demand TLS asks the host app before it requests a certificate, so nobody can make your server request certificates for random names. The host app answers at: ```http GET /_gg/tls-ok?domain=joesplumbing.com ``` It returns `200` for a host name it serves and `404` for anything else. The Caddyfile that ships with the host app uses it like this: ```text { on_demand_tls { ask http://host:8200/_gg/tls-ok } } https:// { tls { on_demand } reverse_proxy host:8200 } ``` It also keeps plain HTTP working for bare IP addresses, so the setup page opens before your DNS is ready, and redirects named hosts to HTTPS. `GET /_gg/health` returns `{ ok, version, paired, sites, uptime }` for monitoring. ### How it talks to your account The host app only makes outgoing requests, so it works behind a home router or firewall as long as it can reach the internet. All requests go to `JAGG_API` and carry the server's connection key as `Authorization: Bearer hst_...`. | Request | What it's for | |---|---| | `POST /api/host/pair` | Exchange a pairing code, or an owner's email and password, for the connection key. Limited to 10 tries per 15 minutes. | | `GET /api/host/sync?version=…&wait=25` | Long poll. Returns the list of sites this server should serve as soon as it differs from `version`, or after `wait` seconds (50 at most). | | `GET /api/host/deploys/:id/archive` | Downloads one uploaded version as a zip. | | `POST /api/host/heartbeat` | Reports the app version, basic stats and the folder names in `sites/`. New folders become sites in your account. | Each site in the sync answer has its host names, its folder name, the version to serve and where to download it, whether to add the widget, and the exact widget ` ``` On Just a Good Guy hosting the server would add this tag for you, but it skips any page that already has one, so keeping it in the files is safe and keeps `data-font="inherit"`. - If the business ever replaces its publishable key, these pages keep the old one. Run `node tools/bake.mjs pk_new_key` and upload again. - Buttons with `data-gg-book`, `data-gg-open` or `data-gg-ask` open the booking or chat panel. Their `href` is the fallback when the widget can't run. - `app.js` replaces the contents of `[data-live]` elements with live data. If the API can't be reached, the content written in the page stays. It never empties a list. - `

` renders the booking flow. The text inside it shows until the widget draws, and stays if it can't.