Start from Apps → New app in your OpenCX dashboard. 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 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.
Preview a draft
The toolbar above the preview holds these controls:
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.
Save, publish and roll back
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.
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.
Other resources appear under their own names, such as Tags or Teams, and need the matching permission in the permissions reference. Every member holds Users · read and Org · read.
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
localhostor private IP ranges, are refused, and so are wildcards over domains shared by unrelated owners, such as*.github.ioor*.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 or workflows, which keep the credentials on the OpenCX side.
Troubleshooting
Related Documentation
Share and use
Roles, editors, Reports & Apps and widgets.
Mini apps introduction
What apps are and who can build them.
Permissions reference
Role permissions an app can need.
Actions
Let apps reach your own systems.