Install on a copy first.
Then connect one channel at a time.

01Requirements

Composer, Node.js and command-line access are not needed to install the module.

02What is in the download

• upload/omnithread.zip: the module. This is the file you upload in Perfex.
• documentation/: this documentation, to open offline.
• licenses/THIRD-PARTY-LICENSES.md: credits and licences.
• README.md: a short pointer to these steps.

03Install and activate

1. Back up. Take a backup of the CRM files and the database you can restore. Try the module on a staging copy of your CRM first if you have one.
2. Check the uploads folder. The web server user must be able to write to the uploads/ folder of your Perfex. On activation the module creates uploads/omnithread/ and writes its encryption key there. If it cannot, the key is kept in the database instead (see The encryption key).
3. Upload the module. In Perfex open Setup > Modules, choose Upload module, pick upload/omnithread.zip and install it. If your host blocks uploads, unzip the file on your computer and copy the omnithread folder into the modules/ folder of your CRM over FTP, so that modules/omnithread/omnithread.php exists.
4. Activate. In Setup > Modules press Activate next to Omnithread - Shared Team Inbox. Activation creates the module's tables and settings and writes the encryption key file. It does not change Perfex's own tables or files. The AI assistant starts switched off.
5. Give staff access. See Staff permissions. Administrators have every permission already.
6. Open the module. The Perfex sidebar now has an Omnithread menu. Open Omnithread > Setup; it starts on Getting started.

04The cron job

Omnithread does its timed work on the Perfex cron job; there is no separate cron command for the module. Set up the Perfex cron as shown in Perfex under Setup > Settings > Cron Job and let it run every 5 minutes. The module registers its own cron task with Perfex when it is active.

On every run the module:

• reads new mail from every active mailbox (a large first import continues on the next runs),
• links new conversations of the last 30 days to customers and leads that were added since,
• sends queued replies and retries failed ones,
• brings snoozed conversations back,
• runs automatic translation for channels where an administrator switched it on (only when AI is on),
• checks SLA timers, sends staff replies written in linked Perfex tickets out to the customer's channel,
• checks channel health and refreshes the report tables for the last two days,
• and once a day cleans up: attachments past their retention setting, old presence marks, webhook log rows older than 14 days and idle website chat sessions.

The System check shows when the cron last ran Omnithread and turns yellow after 15 minutes without a run.

05Staff permissions

Omnithread adds its own permissions to Perfex. Set them per staff member (the staff member's Permissions) or per role. Administrators can do everything.

Each channel also has a Who can use it list (staff members and roles). A non-administrator sees a channel only when they own it, added it, or are on that list. Mailboxes have the same list once they are marked Shared mailbox. Customer, lead, invoice, ticket and project details in the person panel follow the staff member's own Perfex permissions.

06First run: Getting started

Omnithread > Setup > Getting started lists five steps that turn green by themselves: run the System check, connect a channel, create a team, add a rule or an SLA target, and receive your first message.

Sample data (needs the Settings permission) fills every screen so you can look around before connecting a real channel: one switched-off channel of every type, sample people on example.com addresses and +1 555 01xx numbers, three weeks of conversations, a team, a switched-off rule and a switched-off SLA policy. No rule, notification, rating link or SLA alert fires for it. Remove sample data deletes exactly what was created; your own records stay. Remove it before you start with real customers.

Then open System check and fix any red line. Every line says what to do.

07Updating to a new version

1. Back up. Save the database, the modules/omnithread/ folder and the whole uploads/omnithread/ folder. The key file in it is needed to read stored passwords and tokens.
2. Replace the module files. Upload the new omnithread.zip in Setup > Modules, or replace the modules/omnithread/ folder over FTP. Do not delete uploads/omnithread/.
3. Upgrade the database. Do it if Perfex offers it for the module in Setup > Modules. The upgrade, like every activation, adds missing tables, columns, indexes and settings. It never drops a table or a row, and it keeps your settings, channels, conversations and key.
4. Check. Open Setup > System check and send one test message to each channel.

Read the changelog before you update.

08Deactivate

Deactivating keeps every table, setting, file and the key. While the module is off nothing is read or sent, and its public addresses (webhooks, website chat, rating links, the portal page) answer "not found". Messages that providers try to deliver in that time are refused; whether a provider tries again later depends on that provider. Reactivate to continue where you left off.

09Uninstall

• At the providers nothing changes. Remove the webhook addresses in your Meta app and in the Twilio Console yourself. For Telegram, register another webhook for the bot or remove it with the Bot API method deleteWebhook. Remove the website chat line from your website.
• The data folder goes too. Uninstall also removes uploads/omnithread/ with its guard files. A custom storage folder you created yourself stays, empty of Omnithread files.