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.
Where it shows
Section titled “Where it shows”| 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.
The manifest
Section titled “The manifest”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, forgroup.page. It must be an https origin.plan:freeorplus, the plan a group needs for your add-on.points: up to 8, each with its ownkey.
Calls from Grouperly
Section titled “Calls from Grouperly”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:
typisgrouperly-addon-call+jwt,issishttps://app.grouperly.com, andaudis your app’s slug. It lasts 60 seconds. - The body:
bhis 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.
Asking the API as the person
Section titled “Asking the API as the person”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…, answer403 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.
Blocks: cards and panels
Section titled “Blocks: cards and panels”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.
Buttons and selects
Section titled “Buttons and selects”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.
Badges on the attendee list
Section titled “Badges on the attendee list”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
userIdnor acontactId, 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.
Your own page
Section titled “Your own page”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 pageconst { group, api } = await frame.context; // the group, the person, and a tokenconst grouperly = createGrouperlyClient({ baseUrl: api, token: () => frame.token() }); // refreshed when it's close to expiringframe.open(`/groups/${group.id}/events`); // a page of this group in Grouperly; https pages open in a new tabUnderneath, 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.
Developing
Section titled “Developing”Grouperly calls only public https addresses, so expose your local server through a tunnel while you build.