Whoa Chat
Docs

Connector

Optional. The inbox can ask your server what only your app knows about a store: its setup, plan, orders or offers. Answer the questions you want; the inbox hides what you do not answer.

The request

Whoa Chat sends POST to the address registered for your workspace, with a JSON body {op, shop?, ...args} and Authorization: Bearer <token>. The token is an HS256 JWT signed with the connector secret we issue to your workspace, bound to the op, the shop and the exact body, and valid for a minute.

Verify it with verifyConnectorRequest from @whoa-chat/connector. Read the body as text first: the signature covers the exact bytes.

server
// app/routes/whoa-connector.ts
import { verifyConnectorRequest } from "@whoa-chat/connector";

const BEARER = /^Bearer\s+/i;

export const action = async ({ request }) => {
  const token = request.headers.get("authorization")?.replace(BEARER, "") ?? "";
  const raw = await request.text();
  const req = verifyConnectorRequest(process.env.WHOA_CONNECTOR_SECRET, token, raw);
  if (!req) return Response.json({ error: "Not signed." }, { status: 401 });

  switch (req.op) {
    case "storePanel":
      return Response.json(await storePanelFor(req.shop!));
    case "storeStatus":
      return Response.json({ status: await statusesFor(req.body.shops as string[]) });
    default:
      return Response.json({ error: "Not supported." }, { status: 400 });
  }
};

Registering your connector Coming soon During early access we register your connector's address and give you its secret when we set up your workspace.

The questions

Every op is optional. Ops about one store carry shop; team-wide ops do not. The shapes below are the TypeScript types in @whoa-chat/core.

OpWhen the inbox asksAnswer
storePanelA teammate opens a storeStorePanel from @whoa-chat/core/panels: { rows: FactRow[], lastSeenAt?, storefrontUrl? }. Each row has a label and text, strong or chips.
storeStatusThe inbox list shows stores{ status: { [shop]: { tone: "good" | "partial" | "none", label } } }: a dot on each store's avatar.
dashboardThe Analytics page opensDashboard from @whoa-chat/core/dashboard: a title and blocks (stat, list, tiles, line, bars, table, group).
referenceA message names an order, product or offer (ref){ reference: { type, ... } | null }: the preview card for that item, or null when this store has none.
searchA teammate types in the composer's searchItems of this store to link from a reply (offers, products).
actionsThe store panel's activityWhat the merchant did in your admin, newest first.
composerThe card composer opensWhat the composer needs for this store's cards.
merchantA store's details are refreshedThe merchant's details for the store panel.
liveThe live map and online dotsStores with your app open right now.

Other ops (pricing, availability, hours, presence, gifs, reviewQueue and more) power features we enable per workspace; the full list is the ConnectorOp type in @whoa-chat/connector. Answer 400 to anything you do not support.

A store panel

import type { StorePanel } from "@whoa-chat/core/panels";

const storePanelFor = async (shop: string): Promise<StorePanel> => ({
  rows: [
    { label: "Plan", strong: "Growth", text: "since March" },
    { label: "Setup", chips: [{ label: "Widget on" }, { label: "Portal off", muted: true }] },
    { label: "Orders", text: "1,284 in the last 30 days" },
  ],
  storefrontUrl: `https://${shop}`,
});

Timeouts and failures

The inbox waits up to seven seconds. When your server is down or slow, the panels that depend on it say so and the rest of the inbox keeps working.