Whoa Chat
Docs

App events

Installs, setup steps, plan changes and anything else a merchant does in your app can appear on the store's timeline, so your team sees the story before they reply.

Post an event

postChatEvent from @whoa-chat/connector signs the event with your chat secret and posts it to /v1/app/events. It reads SUPPORT_CHAT_API_URL, WHOA_CHAT_SECRET and SHOPIFY_API_KEY from the environment, and does nothing when they are not set.

server
import { postChatEvent } from "@whoa-chat/connector";

await postChatEvent(session.shop, {
  type: "widget_enabled",
  title: "Turned on the storefront widget",
  fields: [
    { label: "Theme", value: "Dawn" },
    { label: "Product", value: "Lavender body oil", url: "https://admin.shopify.com/store/acme/products/123" },
  ],
}, "Acme Store");
FieldRules
typeLowercase letters and underscores, 2 to 40 characters. Types with install or billing in them also go on the team's Activity page.
titleWhat happened, up to 120 characters.
fieldsUp to 30 { label, value, url? }. Links must be https.
nameThe store's name, used when the store has no conversation yet.

Events are for your team only: the merchant never sees them in the chat.

The install event

Send the store's email with the install event, so Whoa Chat can email a merchant who installs, never writes, and later gets a message from your team. Pass a contact token as the fourth argument:

import { contactToken, postChatEvent } from "@whoa-chat/connector";

const contact = contactToken(session.shop, { email: shop.email, owner: shop.shopOwnerName, timezone: shop.ianaTimezone });
await postChatEvent(session.shop, { type: "install", title: "Installed", fields: [{ label: "Plan", value: "Free" }] }, shop.name, contact);

Errors

postChatEvent throws when the chat answers with an error (401 when the signature or the app is wrong). Events are not urgent: send them in the background and log failures rather than failing the merchant's request.