Skip to Content
IntegrationsosTicketPlugin Installation

Plugin Installation

The Flexivity AI plugin is an osTicket plugin distributed as a .phar (PHP Archive) file. It hooks into osTicket’s signal system to capture ticket events and exposes a local REST API that Flexivity AI uses to write back AI-generated results.

Prerequisites

Before installing the plugin, confirm:

  • osTicket 1.17 or 1.18 is installed and running.
  • PHP 8.1 or higher is available on the server running osTicket.
  • You have filesystem access to the osTicket installation directory (SSH or SFTP).
  • You have osTicket admin panel access to activate the plugin.

Warning: The plugin requires PHP 8.1+. If your server runs an older PHP version, the plugin will fail to load and osTicket may display a blank page or PHP fatal error. Check your PHP version with php -v before proceeding.

Step 1: Download the Plugin

Download the latest .phar file from the Flexivity AI GitHub releases page :

# Check the latest release version at the GitHub releases page, then download:
curl -L -o fai-plugin.phar \
  https://github.com/flexivity-ai/osticket-plugin/releases/latest/download/fai-plugin.phar

You can also get the latest plugin .phar directly from the 2nd step of the create instance onboarding wizard, also accessible from the “Edit Setup” button on the instance details page.

Transfer the .phar plugin to your server via SFTP or SCP.

Note: Always use official release builds. Do not manually build .phar files from source for production use, as the build process includes integrity checks and version metadata that manual builds may lack.

Step 2: Install the Plugin File

Copy the .phar file into osTicket’s plugin directory:

# Replace /path/to/osticket with your actual osTicket installation path
cp fai-plugin.phar /path/to/osticket/include/plugins/fai-plugin.phar

Set the correct file permissions so the web server can read the file:

chown www-data:www-data /path/to/osticket/include/plugins/fai-plugin.phar
chmod 644 /path/to/osticket/include/plugins/fai-plugin.phar

Note: The owner (www-data) may differ depending on your OS and web server configuration. On CentOS/RHEL with Apache, use apache:apache. On Nginx, use whatever user your Nginx worker processes run as (check with ps aux | grep nginx).

Step 3: Activate the Plugin

  1. Log in to the osTicket Admin Panel as an administrator.
  2. Navigate to Manage > Plugins.
  3. Click Add New Plugin.
  4. Select Flexivity AI from the list of available plugins.
  5. Click Install.

After installation, the plugin appears in your plugin list. Click on it to open its settings, then set the Status to Active.

Step 4: Configure the Plugin

  1. From the osTicket Admin Panel, navigate to Manage > Plugins and select the Flexivity AI plugin.
  2. Create an instance within the plugin — give it a name and set it to Enabled.
  3. For the configuration, enter the following values from the onboarding wizard (step 2) in the administration console:
    • Instance ID
    • Flexivity AI Base URL
    • Verification Key
    • Deployment type
    • KB AI Search Widget — Enable/Disable
    • KB AI Search Widget — KB Search API Key
    • KB AI Search Widget — KB Search Service URL
    • KB AI Search Widget — Widget Brand Color
    • KB AI Search Widget — Widget Welcome Message
  4. Click Save Changes — it should add the instance successfully.

Step 5: Verify Installation

After activation, confirm the plugin is working:

  1. In the osTicket Admin Panel, go to Manage > Plugins.
  2. The Flexivity AI plugin should show a status of Active.
  3. Check the osTicket system logs (Dashboard > System Logs) for any errors related to the plugin.

You can also verify the plugin’s REST API is responding by running this from the osTicket server:

curl -s http://localhost/api/fai/plugin-info

A successful response returns JSON containing the plugin version and osTicket version. If you get a 404, the plugin is not installed correctly or osTicket’s URL rewriting is not configured for the API endpoint.

Common Issues

Blank Page After Installation

Symptom: The osTicket admin panel shows a blank white page after adding the plugin.

Cause: PHP version is below 8.1, or a required PHP extension is missing.

Fix: Check PHP version with php -v. If below 8.1, upgrade PHP. Also ensure the json, curl, and openssl extensions are enabled (php -m to list loaded modules).

Plugin Not Appearing in “Add New Plugin”

Symptom: The Flexivity AI plugin does not appear in the list when clicking “Add New Plugin.”

Cause: The .phar file is not in the correct directory, or file permissions prevent the web server from reading it.

Fix: Confirm the file is at include/plugins/fai-plugin.phar relative to your osTicket root. Verify the web server user can read the file:

ls -la /path/to/osticket/include/plugins/fai-plugin.phar
# Should show read permissions for the web server user

Permission Denied Errors in Logs

Symptom: osTicket system logs show “Permission denied” errors referencing the Flexivity AI plugin.

Cause: The .phar file or the include/plugins/ directory has incorrect ownership or permissions.

Fix: Re-run the ownership and permission commands from Step 2. Ensure the directory itself is also readable:

chmod 755 /path/to/osticket/include/plugins/

Next Steps

With the plugin installed and configured, proceed to Connecting osTicket to link your osTicket instance to the Flexivity AI cloud, or see the Administration Guide for detailed agent setup instructions.

Last updated on
OverviewConnecting osTicket