Facia Docs
For AI Open Facia
Build on Facia Beta

Build on Facia

There are four ways to add your own things to Facia. Pick the lightest one that does the job.

WayWhoCode?Good for
BlocksOwners and adminsNoPages, polls, scheduled announcements, missions, raffle spins
AppsDevelopersYes, on your serverGames, shops, booking, quizzes, dashboards: anything in a browser, shown as a tab inside Facia
Partner APIYour app's serverYesCharging or paying coins, posting scores, giving badges, posting in groups, push, mission events
EmbedYour website or native appA littlePutting the Facia chat inside your product

Rule of thumb: web things go inside Facia (apps), and native things wrap Facia (embed).

#What an app is

An app is a web page you host, with any stack: plain HTML, React, Vue, Svelte, Phaser, Godot, Unity WebGL, or a no-code tool. Facia shows it in a tab inside a business's app, in the business's colours, and tells your page which client is looking with a signed token.

Apps show up on the Games & more page, in the chat header, or in Membership
Apps show up on the Games & more page, in the chat header, or in Membership
text
 Client's phone                         Your server
┌──────────────────────────┐          ┌───────────────────────┐
│ Facia                    │          │                       │
│  ┌────────────────────┐  │  token   │  verify token (HS256) │
│  │ your page (iframe) │──┼─────────▶│  your data, your rules│
│  └────────────────────┘  │          │                       │
└──────────────────────────┘          └──────────┬────────────┘
                                                 │ partner API (Bearer secret)
                                                 ▼
                                       Facia: coins, scores, badges,
                                       group posts, push, missions

What Facia gives you:

  • Identity: a signed token with the client's per-business id, alias, tier, level and coins.
  • A frame that fits: the business's theme, light or dark, safe-area insets, and a small bridge.
  • An API: partner calls for coins, scores, badges, group posts, push and missions, each scoped to one business, permission-gated and logged.

What you never get: other clients, other businesses, messages, real names, phone numbers, emails or devices. If your server is down, only your tab is down.

#The pieces

  1. Your first app: from zero to a working tab in 15 minutes.
  2. The token: claims, verification in Node, Python, Go and PHP.
  3. The frame bridge: facia-app.js, theme variables, insets and messages.
  4. Partner API: every call, body, response and error code.
  5. Listing your app: offer it to every business on Facia.
  6. Recipes: a coin raffle, a scored game, a daily check-in, a members-only shop.

#Rules for every app

  • No real-money payments or transfers inside the frame, and never ask for card or bank details there.
  • Don't collect names, phones, emails or passwords in the tab. The alias is all you need.
  • Don't pretend to be Facia or the business's support team.
  • Keep your app secret on your server, never in the browser, a repo or a message.

Apps that break these rules get turned off.

#Limits

Up to 20 apps per business. Partner calls: 1,200 an hour per app per business (bursts of 120), and push 120 an hour (bursts of 20). See Limits.

View as Markdown