> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and publish a mini app

> Create a mini app with Companion, preview the draft on real data, publish or roll back versions, and approve the permissions and outside domains it uses.

Companion builds a mini app from your description, you preview the draft on real data, and publishing makes a version live for your team. Read this before you publish: it explains what data and outside services an app can use, and who approves them.

> [!NOTE]
>
> Start from **Apps → New app** in your [OpenCX dashboard](https://platform.open.cx/apps). Requires **Mini apps** and **Companion** with Write access. Publishing also requires every permission the app uses.

## Create an app with Companion

**1. Start a new app**

Open [Apps](https://platform.open.cx/apps) and select **New app**. Companion opens ready to build, with example ideas you can start from.

**2. Describe what you need**

Say what the app should show or do, and whether it belongs beside a session in the inbox or on its own dashboard page. Companion asks when it can't tell.

**3. Review the draft**

Companion builds the app and opens a live preview beside the chat. The result is a draft: nobody else sees it until you publish.

**4. Ask for changes**

Keep asking in the same chat. Each change rebuilds the draft, and the preview updates on its own.

You change an app only through Companion. The **Code** view shows the app's source, read-only. To change an app later, open it from **Apps**, choose **Edit** in an inbox widget's menu, or choose **Open in Companion** on a pinned app under **Reports & Apps**.

## Preview a draft

The toolbar above the preview holds these controls:

| Control | What it does |
| - | - |
| **Preview** / **Code** | Switch between the running app and its source |
| **Reload preview** | Restart the app from scratch |
| Version | Pick **Draft** or a saved version (**v1**, **v2**, …). A green dot marks the live version. |
| **Viewport** | **Desktop**, **Tablet** or **Mobile**. Inbox widgets also offer **Inbox card**, the widget at sidebar width. |
| **Test → Preview session** | Inbox widgets only: the real session the preview uses |
| **Test → Test with live data** | Lets the preview change data and reach outside domains |

A draft, and any saved version that isn't live, behaves differently from a published app:

* **It runs with your permissions.** If the app needs access you don't have, a **Limited access** warning lists what's missing, and those parts fail in your preview.
* **It reads real data but can't change it.** Anything that changes data, such as tagging a session or running an action, shows "This action runs once the app is published." until you turn on **Test with live data**.
* **Outside domains stay blocked** until you turn on **Test with live data**.

**Test with live data** stays on while Companion rebuilds the draft and turns off when you switch versions.

> [!WARNING]
>
> With **Test with live data** on, the preview changes real sessions and contacts and runs your actions for real. Preview inbox widgets on a test session.

## Save, publish and roll back

| Action | Where | What happens |
| - | - | - |
| **Save** | Draft selected | The draft becomes the next numbered version. Nothing goes live. |
| **Publish** | Draft selected | The draft is saved as the next version and goes live in one step. |
| **Publish** | Saved version selected | That version goes live. |
| **Unpublish** | Live version selected | The app goes offline. Anyone using it loses access until you publish a version again. |
| **Delete app** | Trash icon, or **Delete** in the library | The app disappears for everyone, from the library, the dashboard and the inbox. |

One version is live at a time. To roll back, select an earlier version and choose **Publish**: it replaces the live version for everyone. Publishing any version re-checks that you hold the permissions that version uses.

The **Publish** dialog shows two collapsed rows:

* **What this app uses**: the permissions and outside domains this version needs. Choosing **Publish** approves them.
* **Who can open it**: the roles that can open the app, and for inbox widgets, the channels it shows on. Changes here save only when you publish. See [Share and use mini apps](https://docs.open.cx/apps/share-and-use.md).

## What an app can read or change

When Companion builds an app, OpenCX works out which permissions it needs from what it calls. **What this app uses** lists each one as a resource and a verb: **read**, **update**, or another verb such as **invoke** or **trigger**.

* **You must hold every permission yourself to publish**, reads included. Ones you lack are marked "you don't have this", and **Publish** stays disabled.
* **A published app runs with exactly the approved permissions**, whoever opens it. Anything outside that list fails.
* **Sharing doesn't grant access.** People you share with can use the app, but only through the app itself.

> [!WARNING]
>
> A published app shows its data to everyone it's shared with, even people whose own role can't see that data. Share it only with roles that should see what it shows.

Common permissions, and the role permission you need to publish an app that uses them:

| Shown as | Lets the app | Role permission you need |
| - | - | - |
| **Chat sessions** · read | List, filter and read sessions, their messages, tags and handoffs | **Inbox** Read |
| **Chat sessions** · update | Reply, add notes, tag, assign, transfer, hand off or update sessions | **Inbox** Write |
| **Contacts** · read or update | Read or change contact records | **Contacts** Read or Write. **Inbox** Read also covers reading. |
| **Reports** · read | Run report and analytics queries over sessions, CSAT, SLA and agents | **Reports** Read |
| **Actions** · invoke | Run your actions | **Actions** Write |
| **Workflows** · trigger | Run your workflows | **Workflows** Write, or **Run workflows** |
| **Training** · read or update | Read or change AI knowledge base content | **AI knowledge base** Read or Write |
| **Outbound sequences** · read or update | Read sequences, add contacts and run them | **Outbound sequences** Read or Write |

Other resources appear under their own names, such as **Tags** or **Teams**, and need the matching permission in the [permissions reference](https://docs.open.cx/security/permissions-reference.md). Every member holds **Users** · read and **Org** · read.

> [!NOTE]
>
> **Team sessions** or **Assigned sessions** alone don't let you publish an app that reads sessions. Publishing it needs **Inbox** Read.

## Outside domains

By default an app reaches only OpenCX. When it needs something from another site, such as map tiles or a public data source, Companion declares each domain with a reason. The domains and reasons appear under **What this app uses**.

* **The publisher approves them.** Choosing **Publish** approves the domains of the version you publish. A published app reaches only those domains, and can open links to them in a new browser tab.
* **Drafts keep them blocked** until **Test with live data** is on.
* **Some domains aren't allowed.** An app can declare up to 20 domains. Private and internal network addresses, such as `localhost` or private IP ranges, are refused, and so are wildcards over domains shared by unrelated owners, such as `*.github.io` or `*.co.uk`. Declare the specific subdomain instead. Companion is told when a domain is refused.
* **No credentials in apps.** An app can't hold keys or passwords. To reach a system that needs them, the app runs one of your [actions](https://docs.open.cx/actions/introduction.md) or workflows, which keep the credentials on the OpenCX side.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| **Publish** is disabled and the dialog says "Publishing needs access you don't have" | Your role lacks a permission the app uses | Ask someone whose role holds every listed permission, or an admin, to publish |
| "The draft changed while this was open — review it and publish again." | Companion rebuilt the draft while the dialog was open | Review the new draft, then publish again |
| A button in the preview says "This action runs once the app is published." | Drafts can't change data | Turn on **Test → Test with live data**, or publish |
| Map tiles or images from another site don't load in the preview | Outside domains are off for drafts, or the domain isn't declared | Turn on **Test with live data**. If it still fails, ask Companion to declare the domain. |

***

## Related Documentation

> [card] [Share and use](https://docs.open.cx/apps/share-and-use.md)
>
> Roles, editors, Reports & Apps and widgets.

> [card] [Mini apps introduction](https://docs.open.cx/build-agents/mini-apps.md)
>
> What apps are and who can build them.

> [card] [Permissions reference](https://docs.open.cx/security/permissions-reference.md)
>
> Role permissions an app can need.

> [card] [Actions](https://docs.open.cx/actions/introduction.md)
>
> Let apps reach your own systems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.