Whoa Chat
Docs

Quickstart

From an empty workspace to the first merchant message in your inbox. The examples use a Remix or React Router app built with the Shopify app template; any Node server works the same way.

1. Get a workspace Coming soon

Self-serve sign-up is on its way. During early access we create your workspace with you and invite your team; you sign in at app.whoa.chat with email and password, Google or a passkey.

2. Add your Shopify app

In the inbox, open Settings, Apps and add your app with its Shopify client id (the API key in the Partner Dashboard). You get the app's chat secret once: copy it into your server's environment. Owners and admins can add apps and rotate secrets.

.env
# your app's server environment
WHOA_CHAT_SECRET=...            # the chat secret from Settings, Apps
SHOPIFY_API_KEY=...             # your app's client id (you already have this)
SUPPORT_CHAT_API_URL=https://app.whoa.chat

Never send the chat secret to the browser. It signs who the merchant is. Keep it on your server like your Shopify API secret.

3. Install the packages Coming soon

Two packages: @whoa-chat/connector for your server (no dependencies, Node 18 or later) and @whoa-chat/react for the chat in your admin. They will be published to npm; during early access we share them with you directly.

terminal
npm install @whoa-chat/connector @whoa-chat/react @whoa-chat/core

4. Sign the merchant token

Add a route that tells the chat who the merchant in front of it is. It runs Shopify's own authentication, then signs the store and the staff member with your chat secret. The token lives at most an hour; the chat fetches a new one before it expires.

server
// app/routes/api.chat-token.ts
import type { LoaderFunctionArgs } from "@remix-run/node";
import { signMerchant } from "@whoa-chat/connector";
import { authenticate } from "~/shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { admin, session } = await authenticate.admin(request);
  const res = await admin.graphql(`{ shop { email shopOwnerName ianaTimezone } }`);
  const { data } = await res.json();
  const token = signMerchant(process.env.WHOA_CHAT_SECRET!, {
    app: process.env.SHOPIFY_API_KEY!,
    shop: session.shop,
    email: data.shop.email,
    name: data.shop.shopOwnerName,
    timezone: data.shop.ianaTimezone,
  });
  return new Response(token, { headers: { "Content-Type": "text/plain", "Cache-Control": "no-store" } });
};

5. Render the chat

On the client, give the chat a token getter that calls your route. cachedMerchantToken keeps the token until five minutes before it expires. merchantChatApi is the merchant's side of the API: load the thread, send, react, upload.

client
import { cachedMerchantToken, merchantChatApi, toView } from "@whoa-chat/react/chatApi";
import { setChatHost } from "@whoa-chat/react/host";
import "@whoa-chat/react/supportChat.css";

setChatHost({
  brand: { app: "Acme", appFull: "Acme Bundles", team: "Acme support", bot: "Acme", botFull: "Acme AI", logo: "/acme-icon.png" },
});

// App Bridge adds the session token to this same-origin fetch.
const token = cachedMerchantToken(() => fetch("/api/chat-token").then((r) => r.text()));
const api = merchantChatApi("https://app.whoa.chat", token);

const { thread, messages, live } = await api.thread(false);
await api.send("Hi, the widget does not show on my product page", [], "Acme Store", null);

The chat components page shows how to draw the thread with ChatThread and keep it live.

6. See it in the inbox

Open app.whoa.chat. The message is there under the store, with the staff member's name, the store's time zone and anything you sent in the token's store details. Reply, and the merchant sees it in your app; if they have left, Whoa Chat emails them.

Next