# Build on Facia

> The ways to extend Facia (blocks, apps, the partner API and embeds) and which one to pick.

# Build on Facia

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

| Way | Who | Code? | Good for |
| --- | --- | --- | --- |
| **[Blocks](https://docs.facia.chat/business/blocks)** | Owners and admins | No | Pages, polls, scheduled announcements, missions, raffle spins |
| **[Apps](https://docs.facia.chat/build/first-app)** | Developers | Yes, on your server | Games, shops, booking, quizzes, dashboards: anything in a browser, shown as a tab inside Facia |
| **[Partner API](https://docs.facia.chat/build/partner-api)** | Your app's server | Yes | Charging or paying coins, posting scores, giving badges, posting in groups, push, mission events |
| **[Embed](https://docs.facia.chat/setup/embed)** | Your website or native app | A little | Putting 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](https://docs.facia.chat/_assets/shots/client-play.webp)

```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](https://docs.facia.chat/build/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](https://docs.facia.chat/build/bridge).
- **An API**: [partner calls](https://docs.facia.chat/build/partner-api) 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](https://docs.facia.chat/build/first-app)**: from zero to a working tab in 15 minutes.
2. **[The token](https://docs.facia.chat/build/token)**: claims, verification in Node, Python, Go and PHP.
3. **[The frame bridge](https://docs.facia.chat/build/bridge)**: `facia-app.js`, theme variables, insets and messages.
4. **[Partner API](https://docs.facia.chat/build/partner-api)**: every call, body, response and error code.
5. **[Listing your app](https://docs.facia.chat/build/listing)**: offer it to every business on Facia.
6. **[Recipes](https://docs.facia.chat/build/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](https://docs.facia.chat/reference/limits).

> [!AI]
> Want an assistant to build it? Use the Claude Code prompt in [Set it up with AI](https://docs.facia.chat/start/setup-with-ai#build-an-app-with-claude-code-or-any-coding-assistant).