OAPPS for Asterisk — self-hosted installation & updates

This guide installs the OAPPS for Asterisk integration on your own server (the self-hosted option), so your Asterisk / FreePBX phone system creates and updates tickets in Zendesk. It covers both the first installation and later updates.

Installation is manual: OAPPS provides the install command and the software, and you run that one command on your server to download and install it. Nothing is built or compiled on your side.

There are two ways to set it up:

• Managed by OAPPS — we prepare the Zendesk side (the OAuth client and the app). You only run the command and open the app; see the next section.
• Self-service — you do the Zendesk setup too, following the numbered steps in this guide.

If OAPPS set it up for you

When OAPPS has prepared everything, you have only two things to do, and the same command is used for every future update:

1. Run the install command on your server. OAPPS gives you this command with your licence key already filled in — run it on your Asterisk / FreePBX server as root. It downloads and installs the software. To update later, run the exact same command again — unless OAPPS sends you a new command (for example after a licence-key change), in which case run that one.
2. Open the OAPPS app in Zendesk.

The command OAPPS gives you looks like this:

curl -fsSL "https://telephony-api.oapps.io/oapps/control/install" \
  | sudo bash -s -- \
      --control-url "https://telephony-api.oapps.io/oapps/control" \
      --profile selfhosted \
      --key oapps_lic_xxxxxxxxxxxxxxxxxxxxxxxx

That is the whole process when OAPPS set it up — the numbered steps below are only for setting up Zendesk yourself.

Before you begin

Have these ready:

• A server running Asterisk / FreePBX (Debian/Ubuntu based) that you can reach as root (via sudo).
• A public backend domain for that server — a real DNS name reachable over HTTPS with a valid TLS certificate, for example pbx.yourcompany.com. This is the address your Zendesk connects to. An internal IP or a .local name will not work. (If your phone system is on an internal-only network, ask OAPPS about reachability before you start.)
• Administrator access to your Zendesk account.
• Your OAPPS licence key (looks like oapps_lic_…) and the install command — both supplied by OAPPS.

Your backend domain is used in three places — the OAuth redirect URL (Step 2), the app package (Step 3), and the installer (Step 5). Use the same address everywhere.

Step 1 — Create a Zendesk OAuth client

In Zendesk, open Admin Center → Apps and integrations → APIs → OAuth clients, then click Add OAuth client.

Step 2 — Fill in the client and save the secret

Complete the form and Save. The important fields:

Important. If you lose the secret, open the client again and regenerate it — then use the new value. Keep the Identifier and the Secret for Step 5.

Step 3 — Download the OAPPS app package

Open the OAPPS app-package page in a browser: https://telephony-api.oapps.io/oapps/control/get-zendesk-app

Enter your backend domain (the same address as in Step 2, e.g. pbx.yourcompany.com) and click Download .zip. This builds a Zendesk app package pointed at your server. The file carries no secrets — it only embeds the address so the app knows which backend to talk to.

Step 4 — Upload it as a private app

In Zendesk, open Admin Center → Apps and integrations → Zendesk Support apps, then click Upload private app. Give the app a name, upload the .zip from Step 3, and install it.

Note the app name you choose here — you will need it in Step 5 so OAPPS can identify the installed app.

Step 5 — Run the installer

Run the installer on the Asterisk server as root. It is the same command shown earlier, supplied by OAPPS with your licence key in place of the example:

curl -fsSL "https://telephony-api.oapps.io/oapps/control/install" \
  | sudo bash -s -- \
      --control-url "https://telephony-api.oapps.io/oapps/control" \
      --profile selfhosted \
      --key oapps_lic_xxxxxxxxxxxxxxxxxxxxxxxx

The installer then asks a few questions. Each one maps to what you set up above:

About the app id. The same id is used both to verify the app and to create the Talk call records — there is no separate "Talk" id. You can leave it blank: the integration then resolves the real app id automatically from the Marketplace app name — but only if that name matches the installed app exactly. If it does not match, the app sign-in and the Talk call records will not work. For certainty, set the id explicitly: the number is at https://<your-subdomain>.zendesk.com/api/v2/apps/installations.json (your app's app_id), or ask OAPPS to provide it.

A value you have already set is kept and not asked again. Only missing answers are prompted, so you can press Enter through a re-run. The licence key is remembered too.

Step 6 — The other installer options

• Public recordings base URL (Monitor URL). Asterisk records calls to audio files on the server. This is the public HTTPS address where those files are served, so OAPPS can attach a playable recording to the ticket — usually https://<your-backend-domain>/monitor. Your server must actually serve the recording files at that address (OAPPS can help set this up). Leave it blank only if you do not want recordings attached; you can add it later and it will not change call handling.
• API-token fallback (email / token / admin id). An optional alternative to OAuth for authoring tickets. Normally leave all three blank — the OAuth connection in Step 7 is what the integration uses.

Step 7 — Connect and verify

1. Open the OAPPS app in Zendesk and authorise it (Connect) so this server is linked to your Zendesk account.
2. Make a test call and confirm a ticket is created.

If the app keeps asking you to connect, or a call does not create a ticket, re-check the Redirect URL (Step 2) and the app name / app id (Step 5), or contact OAPPS support.

Updating later

When OAPPS releases a new build, run the same command again on the server:

curl -fsSL "https://telephony-api.oapps.io/oapps/control/install" | sudo bash -s -- --profile selfhosted

• Your licence key and all answers are remembered, so the short command above is enough — the installer asks nothing.
• It downloads the latest version, installs it, switches over only if the new version starts cleanly (otherwise it rolls back), then removes the previous version and cleans up temporary files automatically.
• Your configuration is backed up before every run, so a change can be undone.
• To deliberately change a saved answer, add --reconfigure to the command — the installer will then re-ask the questions, offering your current values as defaults.
• If OAPPS rotates or revokes your licence key, the saved key stops working and the download is refused. OAPPS will then send you an updated command containing the new key — run that once (it saves the new key, and later updates are the short command again).

Monitoring

When you deploy locally. You can configure your Zabbix to monitor integration status via HEARTBEAT endpoint. 

https://pbx.yourcompany.com/oapps/control/heartbeat

If service is healthy, you will get 200 response:

{"status":"OK","version":"1.0.4","latest_version_available":"1.0.5","update_available":true}

Need help?

OAPPS support can prepare the Zendesk side with you, supply your licence key and the install command, retrieve your app id, and — with access to the server — run the installer and the updates for you. 

Contact your OAPPS representative support@oapps.io