Skip to main content
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.
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.
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: 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.
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

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.
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: 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 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 or workflows, which keep the credentials on the OpenCX side.

Troubleshooting


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.