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.
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");| Field | Rules |
|---|---|
type | Lowercase letters and underscores, 2 to 40 characters. Types with install or billing in them also go on the team's Activity page. |
title | What happened, up to 120 characters. |
fields | Up to 30 { label, value, url? }. Links must be https. |
name | The 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.