=== CatCode Form Leads to KeyCRM for Contact Form 7 ===
Contributors: catcodestudio
Tags: contact form 7, crm, leads, keycrm, forms
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Sends Contact Form 7 submissions to KeyCRM as orders or lead cards, with product SKU, UTM tags, an email copy, a Telegram copy and a log.

== Description ==

Every Contact Form 7 submission on your site becomes a lead in KeyCRM — no manual copying, no lost enquiries.

The plugin reads the roles of the fields from the Contact Form 7 tag types, so it works with the auto-generated field names Contact Form 7 creates by itself (`text-32`, `tel-635`, `email-278`). Field captions written next to the inputs are reused as human-readable labels in the manager comment.

**What it does**

* Sends every submission to KeyCRM: as an order (`POST /order`) or as a lead card in a pipeline.
* Picks the lead source from the KeyCRM source list, or creates one by name.
* Adds the product name, SKU and price when the form sits on a WooCommerce product page or carries a `product-id` / `product-sku` field.
* Passes UTM tags of the landing page so the CRM analytics knows where the lead came from.
* Sends a copy of the lead by email and to Telegram (a bot chat or a forum topic).
* Keeps a log of every submission in the admin: what went to the CRM, to email and to Telegram.
* Lets you name the lead type per form and switch individual forms off.
* Protects against double submissions: a repeated submission with the same content within five minutes does not create a second lead and does not send a second email.
* Fires the `catcode_lead_captured` action so other plugins (for example CatCode Order Notifications with Telegram) can send their own copy.

This plugin is developed by CatCode and is not affiliated with, endorsed by or sponsored by KeyCRM or the authors of Contact Form 7.

== External services ==

This plugin connects to the following external services. Nothing is sent until you enter your own API key or bot token in the plugin settings.

**KeyCRM API** — https://openapi.keycrm.app

Used to create the lead in your KeyCRM account and to load the list of lead sources shown in the settings.

* `GET /v1/order/source` — when the settings page is opened and when you press "Test connection to KeyCRM". Sends only your API key.
* `POST /v1/order` (order mode) or `POST /v1/pipelines/cards` (lead card mode) — on every accepted form submission. Sends the data submitted in the form: name, phone, email, comment, the values of the other form fields, the lead type, the page URL, the referrer, UTM tags and, when present, the product name, SKU and price.

Terms of use: https://keycrm.app/terms-of-use — Privacy policy: https://keycrm.app/privacy-policy

**Telegram Bot API** — https://api.telegram.org

Used only when you switch the Telegram copy on and enter a bot token and a chat ID. On every accepted submission the plugin sends the same lead fields as a message to the chats you listed.

Terms of service: https://telegram.org/tos — Privacy policy: https://telegram.org/privacy

== Installation ==

1. Install and activate Contact Form 7.
2. Install and activate this plugin.
3. Open Settings → Form Leads to KeyCRM.
4. Paste the API key from KeyCRM → Settings → Open API and save.
5. Pick the lead source, choose the mode and set the lead type for each form.

== Frequently Asked Questions ==

= Do I have to change my forms? =

No. The plugin reads the Contact Form 7 tags, so existing forms work as they are. Field captions become labels in the manager comment.

= Which field becomes the customer name? =

The text field that looks like a name — by its field name or by the caption next to it. If there is no such field, the first text field of the form is used.

= How does the product get into the lead? =

From a `product-id`, `product-sku` or `product` field of the form, or from the WooCommerce product page the form was submitted on. The catalogue data wins over the form values, except that a SKU coming from the form is kept when the product has none.

= What happens if the visitor clicks the button twice? =

The second submission is recognised as a duplicate: the CRM is not called again, no second email is sent, and the log shows the row as a duplicate. The window is five minutes.

= Does it work with the lead card mode? =

Yes, but a pipeline has to exist in KeyCRM first — the API does not create one. Put its ID into the "Pipeline ID" field.

= What is deleted when I uninstall the plugin? =

The settings, the log table and the internal duplicate locks.

== Screenshots ==

1. Plugin settings: KeyCRM connection, lead source, email and Telegram copies.
2. Per-form settings: which forms go to the CRM and the lead type of each.
3. The lead log: what went to the CRM, to email and to Telegram.

== Changelog ==

= 1.2.0 =
* Protection against double submissions: a repeated submission with the same content within five minutes does not create a second lead in the CRM and does not send a second email.
* The Contact Form 7 adapter now respects `$abort`, so a submission stopped by another plugin is no longer sent to the CRM.
* Field captions from the form are used as labels in the manager comment instead of technical field names.
* A clear error is logged when the API key is empty instead of a bare HTTP 401.
* Added `uninstall.php`: settings, the log table and the duplicate locks are removed.
* English source strings with a bundled Ukrainian translation.

= 1.1.0 =
* Email and Telegram copies of every lead, lead type per form, product SKU, admin log.

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.2.0 =
Double submissions no longer create duplicate leads in KeyCRM.
