Catchline docs
v1.0.0
Get help
● Catchline · Start

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

Requirements, upload and activation, the Perfex cron job, staff permissions, the first run, updates, deactivation and uninstall.

About 15 minutesNo Perfex core files are changed

01Requirements

WhatNeededWhy
Perfex CRM 3.2 or newerRequiredBought separately. The download does not include Perfex.
PHP 8.1 or newerRequiredThe System check fails on older versions.
PHP extensions curl, mbstring, openssl, jsonRequiredLead Ads, conversions, captcha checks, webhooks and AI calls; texts in every language; encrypted secrets.
PHP extension fileinfoRequired for file uploadsThe type of an uploaded file is read from its content. Without fileinfo every upload in a form is refused. The System check does not test it.
stream_socket_client not disabledFor reply mailboxesReply mailboxes are read with the module's own IMAP client; the PHP imap extension is not needed.
MySQL or MariaDBRequiredThe database your Perfex already uses. The module adds 35 tables with your Perfex table prefix.
The Perfex cron jobRequiredRetries, the lead watcher, reply timers, claims, sequences, reply mailboxes, outgoing webhooks, conversions, score decay and clean-up all run on it.
A public https:// address for the CRMRequired for most sourcesMeta, Google Ads and the form tools post leads to your CRM. Hosted forms, embeds and unsubscribe links are public pages too.
Outgoing e-mail set up in PerfexRequired for sequences and alertsFollow-up e-mails and e-mail alerts are sent through Perfex's own e-mail settings (Setup > Settings > Email).
A writable uploads/ folderRequired for uploads and CSV importThe module keeps form uploads and CSV files waiting for import in uploads/catchline-private/.
PHP memory_limit 128M or more, uploads of 10 MBRecommendedThe System check warns below 128M and when PHP accepts uploads smaller than 10 MB (the CSV limit).

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

02What is in the download

  • upload/catchline.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.
Upload the inner ZIP only

Do not upload the whole download as a module. Unzip it first and use upload/catchline.zip.

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. Catchline creates uploads/catchline-private/ the first time a form receives a file or you preview a CSV file.
  3. Upload the module. In Perfex open Setup > Modules, choose Upload module, pick upload/catchline.zip and install it. If your host blocks uploads, unzip the file on your computer and copy the catchline folder into the modules/ folder of your CRM over FTP, so that modules/catchline/catchline.php exists.
  4. Activate. In Setup > Modules press Activate next to Catchline - Lead Capture, Routing And Follow-up. Activation creates the module's 35 tables and its settings and a random signing secret. It does not change Perfex's own tables or files. The AI helper starts switched off.
  5. Give staff access. See Staff permissions. Administrators have every permission already.
  6. Open the module. The Perfex sidebar now has a Catchline menu. Open Catchline > Setup; it starts on Getting started.
  7. On nginx: add the deny rule for uploads/catchline-private/ from Security hardening.

04The cron job

Catchline does its timed work on the Perfex cron job; there is no separate cron command for the module. Set up the Perfex cron as Perfex shows it under Setup > Settings > Cron Job. Run it every 5 minutes or more often: reply timers, claim offers and Lead Ads retries are only as precise as the cron.

On every run the module:

  • retries failed submissions that are due (after 5, 30, 120 and 360 minutes, up to the Automatic retries setting),
  • removes payloads older than the retention period and old unfinished answers,
  • writes message summaries when the AI helper and automatic summaries are on,
  • looks at the Perfex leads Catchline captured for status changes, notes, contacts, activity and conversion to a customer,
  • checks reply timers (reminder, late, reassign, escalate) and expires claim offers,
  • sends the follow-up e-mails and tasks that are due and reads the reply mailboxes,
  • sends outgoing webhooks and Meta conversion events, with retries,
  • lets behaviour points of scores fade, reads Lead Ads leads again whose first reading failed, and clears old visit counters.

Each step has a time budget, so a busy run finishes on the next one. The System check shows when the cron last ran Catchline and warns after 30 minutes without a run.

05Staff permissions

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

Permission (as shown in Perfex)What it allows
ViewOpens the dashboard, forms, sources, the submission log, the review queue, lead panels, scoring and routing, the sales team, sequences and reports. Previews forms. Exports report CSV files.
Create connectionsAdds sources, forms (also by duplicating), sequences and CSV imports. With the AI helper on: asks for form drafts and e-mail drafts.
Edit connections, replay and decideChanges sources, mappings, rules, duplicate settings and secrets; edits, publishes and archives forms, variants and placements; replays submissions; decides in the review queue; edits score rules, sales team entries, sequences and ad costs; approves or rejects AI proposals.
DeleteDeletes sources, forms without answers, submissions from the log, sequences and ad costs.
Claim leads offered to a poolSees Claim leads and takes leads a routing rule offers to a pool the person is in. A staff member with only this permission sees only that page.
Administrators only

Settings (API keys, captcha keys, the Telegram bot token, reply mailboxes, privacy tools), Conversions, Outgoing webhooks, the System check, sample data and the AI connection test are open to Perfex administrators only, whatever the permissions.

The lead panel, hot leads and AI score explanations follow Perfex's own rule for leads: staff without "view all leads" see only leads assigned to them, added by them or marked public.

06First run: Getting started

Catchline > Setup > Getting started lists six steps that turn green by themselves: run the System check, connect a source, map the fields, route leads to your team, switch on a follow-up sequence, and send conversions to your ad platforms.

Getting started with six setup steps, each with a button that opens the right screen
Getting started

Sample data (administrators, on the same page) fills the screens so you can look around first: sample leads with scores and sources, a sample sequence and report figures. Sample records live only in Catchline's own tables; nothing is added to your Perfex leads, customers or tickets, sample sources, rules and the sequence stay switched off, and nothing is sent. Remove sample data deletes exactly the sample records. Remove it before you start with real leads.

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

System check with PHP version, extensions, tables, cron, encryption, private storage, outgoing e-mail, failed submissions, reply mailboxes, outgoing webhooks, memory and upload size
System check. Two rows ask for a look here: the sample data has two failed submissions and the test server accepts uploads of only 2 MB.

07On the Perfex lead page

For leads Catchline captured or scored, the Perfex lead page shows a small Catchline: score button (or Catchline: source and speed) that opens the lead panel with the score, the reply timer, the source and campaign and the follow-up. Perfex documents no hook for a tab on the lead page, so the module adds this button at the bottom of the page.

08Updating to a new version

  1. Back up. Save the database, the modules/catchline/ folder and the whole uploads/catchline-private/ folder (stored form uploads).
  2. Replace the module files. Upload the new catchline.zip in Setup > Modules, or replace the modules/catchline/ folder over FTP. Do not delete uploads/catchline-private/.
  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, sources, forms and the signing secret.
  4. Check. Open Setup > System check and send one test lead through each source.

Read the changelog before you update.

09Deactivate

Deactivating keeps every table, setting and file. While the module is off nothing is captured or sent: built forms and embeds answer "not found", the webhook and Lead Ads links answer "Catchline is not active on this site" (HTTP 503), and the Google conversion file, tracking and unsubscribe links answer "not found". Leads that providers try to deliver in that time are refused; whether a provider tries again later depends on that provider (Meta retries for up to 36 hours; you can also fetch missed Lead Ads leads, see Fetch leads you missed). Reactivate to continue where you left off.

10Uninstall

Uninstall deletes the module's data

Uninstall removes all 35 Catchline tables (sources, forms, the submission log, scores, sequences, reports, logs), every Catchline setting including saved keys and tokens, and the files forms stored. Export what you need and back up first. Leads, customers, contacts, tickets, tasks and notes Catchline created are Perfex records and stay, and so do files already attached to Perfex leads.

  • At the providers nothing changes. Remove the webhook in your Meta app and in Google Ads, the webhooks or scripts in your form tools, and the embed codes on your website yourself.
  • On disk: uninstall also removes uploads/catchline-private/ with its guard files and its import/ folder (or, with your own storage folder, everything Catchline wrote there). A file Catchline did not write stays, and so does its folder.