PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub
Community appsQuickstartIdentity tokenAPI accessApp webhooksTesting your apppostMessage protocol

API

Community apps

Community apps

Build apps that run inside a Planeward community as an iframe.

A community app is your own web app, served over HTTPS, that Planeward renders in an iframe inside a community. The app learns who is viewing from a signed identity token, and its backend can call back into Planeward with the scopes the installer approved: read members, channels and courses, post messages, track course progress, register members for events, submit forms for them, award badges and send them notifications.

The workspace that installs an app needs the Community feature on its plan. Apps run in the community only; a workspace with just Commerce has nowhere to install them. For what community owners and members see, point them to Apps in your community.

Where apps appear

  • Experience — a channel in the member community. Members open it like any other channel.
  • Dashboard — a staff view under Community › Apps in the workspace.

The token tells you which one you are in (view is experience or dashboard).

Notifications

An app can notify members with COMMUNITY_NOTIFICATIONS_WRITE. The notification shows in the member's bell and as a push notification, titled with your app's name, and a click opens your app at a path you choose (deep links). Members can switch an app's notifications off, and the app is never told. See Notifications in the API.

Mentions work for apps too. A message an app posts can mention a member with @[memberId]. In the other direction, message bodies and community.message.created events can now contain mention tokens (@[id], #[id] and @everyone) that your app has to read or strip. Mentions in messages members write notify the people mentioned, not your app; an app is told about them only through the message event.

Private and official apps

An app belongs to the workspace that built it. A private app can be installed by that workspace, and by anyone holding its secret install link. The link is unlisted, so an agency can ship one app to many client workspaces. Official apps are published by Planeward.

Lifecycle

  1. Create — Settings › Apps › Developer. Set the app URLs, webhook URL and requested scopes. Copy the app secret; it is shown once. While you build, the app URLs can point at localhost (Testing your app).
  2. Install — from your workspace or the install link. The installer approves the requested scopes.
  3. Add as a channel — staff add the app to the community as a channel.
  4. Uninstall — removes the app's channels, revokes its API access, hides its badges and sends app.uninstalled. Messages the app already posted stay. Reinstalling brings the badges and their awards back.

SDK and template

  • @planeward/sdk (source) — the iframe handshake and viewer token in the browser, plus token verification, webhook verification and a typed API client on your server.
  • Planeward app template — a Next.js starter built on the SDK, with a member experience, a staff dashboard, webhooks and a Postgres database.

Next

  • Quickstart
  • Identity token
  • API access
  • Webhooks
  • Testing your app
  • postMessage protocol

Developer hub

Create an API key, register a webhook, or connect MCP.

Quickstart

A Next.js community app that greets the viewer by name.

On this page

Where apps appearNotificationsPrivate and official appsLifecycleSDK and templateNext