Build a mini app
A mini app is a web page you host that the panel shows as a tab beside the contact details in a conversation, or as a full page of its own.
- Plan
- Depends on your plan · Which plan do I need?
- Who can use this
- Developer, Account owner
A mini app is a web page you host that the panel shows as a tab beside the contact details in a conversation, or as a full page of its own.
A mini app is a web page you host that the panel shows as a tab beside the contact details in a conversation, or as a full page of its own. It receives the open conversation as a signed token, matches the panel's theme, and can act back on the inbox: stage a draft reply, show a dialog, tag, note or close a conversation. It can never send a message by itself; a person always presses send.
Settings → Integration → Mini Apps (marked Beta). The Your own apps part of the page is where you add a private app. You need the Manage Settings permission.
miniapps). Hosting your own page also needs the Custom Apps add-on (custom_apps). Without it the section shows "Not included in your plan" and a See add-ons button.frame-ancestors in your Content-Security-Policy must name the panel's address).instructions/ folder contain the developer guide, the protocol reference, token verification and a protocol debugger.With both ticked you can set Different address for the full page.
Their server checks the sign-in token against this value.
The icon has no label; hover shows "Remove" and the app's name.
Agents no longer see its tab. Your app itself is not affected, and you can add it back at any time. Click Keep it to cancel.
Nothing works until the page announces itself.
A line your server posts into a conversation (POST /v1/conversations/{id}/system-messages) can open your conversation tab. Put "mini_app": { "slug": "<your app's slug>", "ref": "<your reference>" } in the message's meta.
systemMessage.open event with { ref, conversationId }, so you can show the record the line is about.ref is optional, up to 200 characters. mini_app is never shown under the message's details.mini_app only when the panel announces the systemMessage.open capability (hasCapability("systemMessage.open")). An older panel shows it under the message's details.ref as untrusted: look it up within what the verified context token allows.| Permission | Grants |
|---|---|
conversation:read | Conversation id, state, assignment |
contact:read | Contact name and phone |
contact:fields | The contact's custom fields |
channel:read | Channel id, name, phone number id |
messages:read | The last few messages, with content |
composer:write | Stage a draft reply, a file, a rich message or a template |
conversation:write | Tag, note, remind, assign, close |
host:ui | Toast, confirm dialog, in-app navigation |
Actions are also limited by the agent's own role. An app with conversation:write still cannot close a conversation for an agent who is not allowed to.
miniapps); your own apps also need the Custom Apps add-on (custom_apps). Check Billing → Current Plan.companyId. This keeps tenants apart if you publish the app later.miniapp:<installation id> to miniapp:<slug>, and existing installs keep the old one.The Copilot cannot add or edit private apps; use the Mini Apps screen. It can list catalog apps: "Which mini apps can I install?"
| What you see | Why | What to do |
|---|---|---|
| Blank tab, console shows a CSP / frame-ancestors error | Your server forbids framing | Add the panel's address (and http://localhost:3000 for local work) to frame-ancestors |
| Panel loads but does nothing | ready() was never called | Call ready() at startup |
| Your server answers 401/403 | Wrong audience, issuer or JWKS | Use the App ID as audience; accept a list |
| Your server answers 503 | Verification is not configured | Set the JWKS URL, issuer and audience on your server |
Action returns denied | The agent's role does not allow it | Disable that control for the agent |
Action returns missing_scope | Permission not ticked | Tick it under What this app is allowed to do |
| "Fix the highlighted fields first" | A required field is empty or invalid | Correct the fields |