Connecting osTicket

Connecting osTicket takes three steps. The setup wizard walks you through them: start from the setup card on your dashboard, or open Help Desk in the admin console at app.flexivity.ai .

1. Choose how Flexivity reaches your osTicket
2. Install and configure the plugin
3. Connect, directly or through the agent

Before you begin

1. Choose how Flexivity reaches your osTicket

When you register the instance, choose one of two modes:

• Direct connection (in the console: Shared Hosting (cloud-managed)). Use it when your osTicket is reachable over the internet, for example on a hosting provider. Flexivity connects to the plugin from the cloud, and there is nothing to run on your side. Payment card, government and bank identifiers are masked as the data arrives in the Flexivity cloud, and personal information is scrubbed before anything is stored.
• On-premise agent (in the console: Self-Hosted (on-premise agent)). Use it when your osTicket is behind a firewall or on a private network. A small Docker container runs alongside osTicket and connects out to Flexivity, so no inbound ports are opened, and payment card, government and bank identifiers are masked before anything leaves your network. Personal information is scrubbed in the Flexivity cloud before anything is stored.

You can change the mode later with Edit Setup on the instance’s Help Desk page.

2. Install and configure the plugin

Both modes need the Flexivity AI plugin in osTicket. The wizard’s Install osTicket Plugin step has the plugin file and the values it needs. To see them again later, click Edit Setup on the instance’s Help Desk page.

Note: The plugin needs PHP 8.1 or higher. On an older PHP, osTicket may show a blank page once the plugin is added. Check with php -v first.

Download the plugin

Click Download Plugin (.phar) in the wizard, and copy the file to your osTicket server.

Copy it into osTicket

Put the file in osTicket’s plugin directory and let the web server read it:

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

The owner depends on your server: www-data on Debian and Ubuntu, apache on CentOS and RHEL with Apache, or the user your Nginx and PHP-FPM workers run as.

Activate it

1. In the osTicket Admin Panel, go to Manage > Plugins.
2. Click Add New Plugin, select Flexivity AI, and click Install.
3. Open the plugin and set its Status to Active.

Configure it

In the plugin, add an instance, name it, set it to Enabled, and copy in the values from the wizard:

• Instance ID
• FAI Base URL: the wizard’s Flexivity AI Base URL
• Verification Key (RSA Public Key)
• Deployment Type: Self-Hosted (Agent) or Shared Hosting, as you chose in step 1

The KB AI Search Widget fields set up the search box on your public pages: Enable KB Search Widget, KB Search API Key and KB Search Service URL from the wizard, plus a Widget Brand Color and Widget Welcome Message of your choice. Leave the widget disabled if you do not want it yet. See KB AI Search.

Click Save Changes.

Check the plugin is answering

From the osTicket server, run:

curl -s -o /dev/null -w "%{http_code}\n" https://your-osticket/api/fai-plugin/v1/plugin-info

401 means the plugin is installed and answering, and is refusing you only because the request is not signed by Flexivity. 404 means osTicket is not routing to the plugin: check that it is installed and active. See Troubleshooting: osTicket.

Connecting Directly

With the plugin installed, the wizard’s final step is Connect osTicket.

Step 1: Test the connection

1. Click Test Connection.
2. Flexivity tries to reach the plugin at your osTicket’s address.
3. If it succeeds, you see Connected, with the plugin version. If it fails, the message says why; see Test Connection fails.

Step 2: Check the heartbeat

On the instance’s Help Desk page:

1. The status shows Active.
2. The Last heartbeat time updates regularly.

Step 3: Check the plugin details

The Plugin Info section shows the plugin version and the osTicket version.

If these are empty, or the heartbeat does not update, check that your osTicket’s firewall allows inbound HTTPS from the Flexivity AI cloud, and that the plugin is installed and active.

Agent Setup

With the plugin installed, the wizard’s final step is Connect Agent. The agent runs as a Docker container alongside osTicket and keeps a secure outbound connection to the Flexivity AI cloud.

Prerequisites

• Docker Engine 20.10+ and Docker Compose v2 on a server that can reach your osTicket
• Outbound network access on port 443 (WSS and HTTPS)

Step 1: Download the Docker Compose file

In the Connect Agent step, click Download docker-compose.yml. The file comes with your instance’s credentials already filled in, and downloads as docker-compose.fai-agent.yml. On the server that will run the agent, put it in a directory of its own and rename it docker-compose.yml, so the commands below find it.

Step 2: Start the agent

In the directory containing docker-compose.yml, run:

docker compose up -d

The agent starts, connects to the Flexivity AI cloud, and begins relaying events between osTicket and Flexivity.

Step 3: Check the connection

On the instance’s Help Desk page:

1. The status changes from Pending to Active.
2. The Last heartbeat time updates within a minute.
3. The Plugin Info section shows the plugin and osTicket versions.

Network requirements

The agent needs outbound access only:

• WSS (port 443) to the Flexivity AI cloud, for the connection that carries events and commands
• HTTPS (port 443) to app.flexivity.ai, for API calls and health checks

No inbound ports need to be opened.

The agent also calls your osTicket’s plugin API at the osTicket URL you entered. If that URL is HTTPS, the agent checks osTicket’s certificate and refuses the connection if the certificate isn’t trusted, because those calls carry the agent’s credentials and ticket content. A certificate from a public authority works with no extra steps.

If osTicket uses a self-signed certificate, or one from your organization’s own certificate authority, give the agent that certificate. Save it as a PEM file next to docker-compose.yml, mount it, and set FAI_OSTICKET_CA_FILE to its path in the agent’s service:

    environment:
      FAI_OSTICKET_CA_FILE: /etc/fai/osticket-ca.pem
    volumes:
      - ./osticket-ca.pem:/etc/fai/osticket-ca.pem:ro

For a self-signed certificate, the file is the certificate itself. For your own authority, it’s the authority’s certificate. The agent trusts it in addition to the public authorities, and only for its calls to osTicket. The certificate must name the host in your osTicket URL. If the file is missing, the agent won’t start. Certificate checking can’t be turned off.

Updates

The agent updates itself automatically. New instances use the Stable update channel, which receives updates after they have been tested; you can change the channel on the instance’s Help Desk page. See Agent Health.

Stopping and restarting the agent

To stop the agent:

docker compose down

To start it again:

docker compose up -d

The agent reconnects on its own. The instance briefly shows as Disconnected during the restart and returns to Active once it is back.

Looking up and changing customer records

If you use data connectors (Stripe, Zapier or your own systems), the AI can look up a ticket requester’s own record before it replies. Lookups need Flexivity plugin 2.9.0 or later, and a self-hosted install also needs agent 1.5.0 or later; an older install gets no lookups and replies exactly as before. The requester’s email addresses are read from your osTicket at the time of each lookup and are never stored.

Set “Require registration and login to create tickets”. In osTicket’s Admin Panel, under Settings → Users, set Registration Required so customers must sign in to open a ticket. osTicket does not check the email address of someone who opens a ticket without signing in, so with this off, anyone could open a ticket under a customer’s address, and Flexivity cannot tell. With it on, a ticket opened through your web portal counts as coming from a signed-in customer.

Changes such as a refund work the same way on every ticket when an agent approves each one: the agent reads the ticket and decides, and Flexivity only allows a change to the requester’s own record. Changes the AI would make on its own, without an agent, are planned for later and will need a signed-in customer, so they will need registration and login required.

Troubleshooting

If the instance stays Pending, see Troubleshooting: osTicket. To rotate the plugin’s keys, see Instance Setup.