Skip to content

Add-ons

An add-on is an app that shows inside Grouperly’s pages, for the groups that add it. It’s still your app, on your own server and site, built on the Platform API. Grouperly draws your cards and panels with its own look, and it opens your own pages in a frame inside the group.

Spot Where How
group.card A card on the group’s overview Grouperly draws your answer
event.panel A panel on an event’s page, under its details Grouperly draws your answer, with buttons and a select
event.attendee A badge beside each person on an event’s attendee list Grouperly asks once for the whole list
group.page An entry under Add-ons in the group’s menu, opening your page Your site, in a frame

A spot shows only to someone who can open its page, never on a child’s account. It shows only while the group has your add-on on a plan that covers it.

Your app’s registration says where it shows:

"addon": {
"plan": "free",
"backendUrl": "https://checklist.example/grouperly",
"frameOrigin": "https://checklist.example",
"points": [
{ "key": "lists", "point": "group.page", "title": "Checklists", "path": "/lists" },
{ "key": "packed", "point": "event.panel", "title": "Who's packed" },
{ "key": "status", "point": "event.attendee", "title": "Packing" },
{ "key": "next", "point": "group.card", "title": "Next trip" }
]
}
  • backendUrl: where Grouperly calls you for what it draws. It must be https on a public address.
  • frameOrigin: your site, for group.page. It must be an https origin.
  • plan: free or plus, the plan a group needs for your add-on.
  • points: up to 8, each with its own key.

For each card, panel and attendee list it draws, Grouperly POSTs JSON to your backendUrl:

{
"point": "event.panel",
"key": "packed",
"group": { "id": "…" },
"event": { "id": "…" },
"viewer": { "id": "…", "token": "…", "tokenExpiresAt": "2026-10-20T15:10:00.000Z" },
"api": "https://app.grouperly.com/api/v2"
}

Check every call. Each one has Authorization: Bearer <token>, a JWT signed with Grouperly’s own key.

  • The key: ES256, published at https://app.grouperly.com/.well-known/jwks.json.
  • The token: typ is grouperly-addon-call+jwt, iss is https://app.grouperly.com, and aud is your app’s slug. It lasts 60 seconds.
  • The body: bh is the SHA-256 of the exact body, in base64url.

@grouperly/sdk/addon does all of this:

import { addonApi, verifyAddonCall, type BlocksAnswer } from '@grouperly/sdk/addon';
export async function POST(request: Request) {
const call = await verifyAddonCall(request, { slug: 'checklist' }); // throws AddonCallError: answer 401
const grouperly = addonApi(call); // the API, as the person looking
const { data: group } = await grouperly.GET('/groups/{groupId}', { params: { path: { groupId: call.group.id } } });
return Response.json({ blocks: [{ type: 'heading', text: `${group!.name}'s next trip` }] } satisfies BlocksAnswer);
}

Answer quickly. You have 1.5 seconds and 32 KB while the page is built. If you miss that, the person’s browser asks again through Grouperly with 8 seconds, so a cold start gets a second chance. After that, the spot says your add-on couldn’t load, with Retry.

Keep nothing of what Grouperly sends beyond answering it.

viewer.token lets you ask the Platform API as the person looking, so you never take Grouperly’s word for anything. Send it as Authorization: Bearer ….

  • Time: it lasts 10 minutes. Each call brings a fresh one.
  • Place: it works only on the endpoints of the call’s group (/groups/{groupId}/…). Another group’s endpoints, and /me…, answer 403 forbidden.
  • What it may do: what your app is registered for, what the group allowed when it added you, and what the person may do there, the same as an app’s access token. Removing your add-on, or the person leaving the group, stops it at once.

Answer a card or a panel with { "blocks": [...] }. Grouperly draws each block with its own pieces, and every string is shown as text, never HTML.

Block Fields
heading text
text text, muted
stat value, label
badge text, tone
list items: text, detail, badge
table columns, rows
link text, href: a page on your own frameOrigin, over https; it opens in a new tab
button id, label, style (primary or secondary), confirm
select id, label, options (value, label), value

Tones are gray, blue, green, yellow, red and purple.

Limits:

  • 20 blocks, and 5 buttons and selects, each with its own id;
  • text up to 500 characters, and headings, labels and options up to 80;
  • 50 list items, and tables of 6 columns and 50 rows.

ADDON_LIMITS in the SDK has them all. An answer over a limit, or malformed, isn’t drawn: the spot says your add-on couldn’t load. A block type Grouperly doesn’t know yet is skipped.

To hide the spot from this person, answer with no blocks, or an empty body.

When someone presses a button or picks an option, Grouperly calls you again, as them, with "action": { "id": "remind", "value": null }. A select’s value is the option chosen. Answer with the spot’s new blocks, and a notice to show under them:

{ "blocks": [ … ], "notice": "Reminders sent to 3 families" }

Grouperly keeps no answer, so check the action’s id against what you drew, and the person’s rights through the API.

For event.attendee, the call has attendees: the people going or maybe going, as the person looking sees the list.

{ "attendees": [{ "id": "…", "userId": "…", "contactId": "…", "status": "GOING" }] }
  • A name typed in has neither a userId nor a contactId, so you can say you don’t know them.
  • Youth are included only for an add-on allowed to see them. Any other is told only about adults’ accounts.

Answer with a badge for each attendee id you know about:

{ "badges": { "<attendee id>": { "text": "Packed", "tone": "green" } } }

Grouperly ignores ids it didn’t send you.

A group.page spot opens your site (frameOrigin + path) in a sandboxed frame inside the group’s page. It runs as your own site, so your sign-in and storage work. It can’t navigate Grouperly’s tab.

@grouperly/sdk/frame talks to Grouperly for it:

import { connectToGrouperly } from '@grouperly/sdk/frame';
import { createGrouperlyClient } from '@grouperly/sdk';
const frame = connectToGrouperly(); // keeps the frame as tall as your page
const { group, api } = await frame.context; // the group, the person, and a token
const grouperly = createGrouperlyClient({ baseUrl: api, token: () => frame.token() }); // refreshed when it's close to expiring
frame.open(`/groups/${group.id}/events`); // a page of this group in Grouperly; https pages open in a new tab

Underneath, it’s postMessage with https://app.grouperly.com only:

Your page sends Grouperly
{ type: "grouperly:ready" }, then { type: "grouperly:token" } for a fresh token { type: "grouperly:context", group, viewer, api }, or { type: "grouperly:unavailable" }
{ type: "grouperly:resize", height } sets the frame’s height
{ type: "grouperly:open", href } opens one of this group’s pages, or an https page in a new tab

Send your pages with Content-Security-Policy: frame-ancestors https://app.grouperly.com, so only Grouperly can frame them. Grouperly allows your site in a frame when your add-on is registered.

Grouperly calls only public https addresses, so expose your local server through a tunnel while you build.