=== ConvoHub ===
Contributors: convohub, shivampatel, ceowizzyweb
Tags: live chat, chat widget, leads, contact form, customer support
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.4.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect your site to ConvoHub: add the chat widget, recognize signed-in customers, and send contact-form leads to your ConvoHub inbox.

== Description ==

ConvoHub for WordPress connects your website to your [ConvoHub](https://convohub.io) account.

**Chat widget**

* Pick the website inbox that powers your chat, or create one for your site in a click.
* Choose where the widget shows: every page, only some pages, or every page except some. Hide it for signed-in users or on the WooCommerce checkout.
* Set the position, launcher style, color scheme and other options.
* Warns you when your inbox's allowed-domains list would make the browser block the widget, and fixes it in a click.

**Recognized customers**

* Signed-in customers are signed on your server, so ConvoHub knows who they are and shows their conversation history on any device.
* The chat resets when someone signs out or a different person signs in on the same browser.

**Lead collection**

* Add the "ConvoHub Lead Form" block, or use the `[convohub_form]` shortcode.
* Choose the fields: rename, reorder, hide or require the built-in ones, and add your own (short or long text, number, email, phone, dropdown, checkbox), such as Company or Budget.
* Style the form with your own CSS from the Leads tab.
* Each submission becomes a contact and a conversation in a ConvoHub API inbox, tagged with the page and campaign (UTM) it came from.
* Phone numbers are converted to international format. Spam is limited with a hidden field and a per-visitor rate limit.
* If ConvoHub cannot be reached, the lead is kept and retried automatically. You can see, resend or discard undelivered leads under ConvoHub > Logs.

**Help built in**

* A Help tab with searchable guides, a setup guide that ticks itself off, and a diagnostics panel you can copy for support. It never includes your token or secrets.
* A setup checklist on the Connection tab shows what is left to do.

**Events from ConvoHub**

* A signed webhook receiver lets ConvoHub tell your site about new customer messages. Each event is verified, checked for age, and processed once. Developers can react to events with the `convohub_webhook_event` action.

A companion plugin, ConvoHub Commerce, adds WooCommerce cart recovery and order-aware support. It requires this plugin.

== Installation ==

1. Upload the plugin and activate it.
2. In ConvoHub open Settings > Integrations > WordPress and generate a connection key. In WordPress go to ConvoHub in the admin menu, paste the key into "Connection key" on the Connection tab and press Connect.
3. On the Widget tab, choose or create the website inbox and turn the widget on.
4. On the Leads tab, choose or create the API inbox that receives leads, then add the lead form to a page.
5. Optional: on the Connection tab, register the webhook so ConvoHub can send events to your site.

== Frequently Asked Questions ==

= Where is the help? =

Open ConvoHub in the admin menu and choose the Help tab. It has guides for every setting, a step-by-step setup guide and diagnostics. Small question-mark links next to the more complex settings open the right guide.

= What does "Copy for support" copy? =

A short list of facts about your site and settings (versions, whether the widget and webhook are on, and so on). Your connection key, access token, identity secret and webhook secret are never included, and anything that looks like a secret is removed from the text.

= Where do I find my connection key? =

In ConvoHub, open Settings > Integrations > WordPress and generate a key. Only a ConvoHub administrator can do this. Paste the whole key into the Connection tab. A key works once and is not saved.

= It says the key is not valid. =

The key may have been used already, revoked or expired, or its owner is no longer an administrator. Generate a new one in ConvoHub. The Help tab explains each message.

= My site was connected with an API access token before. =

It keeps working. The Connection tab shows a notice until you replace the token: generate a key in ConvoHub and paste it. If the key belongs to the same account, your inbox, identity and webhook settings stay.

= The widget does not appear. =

Check that the widget is turned on, that the page is not excluded by your display rules, and that your site's address is in the inbox's allowed domains. The Widget tab shows a warning and a one-click fix if it is not.

= How do I add my own form field? =

Go to ConvoHub > Leads > Form fields and choose "Add a field". Give it a label and a type. The value is added to the first message of the conversation and saved on the contact in ConvoHub under the field name. Changing a field's name later starts a new attribute in ConvoHub, so choose it once.

= How do I style the form? =

Use the Appearance section on the Leads tab: a button colour, the corners, the space between fields and a maximum width. What you leave on "Follow the theme" keeps your theme's look. For anything else use WordPress's own Additional CSS (Appearance > Customize, or Styles in the Site Editor) with the form's classes: `convohub-lead-form`, `convohub-lead-form__field`, `convohub-lead-form__field--email` (or any field name), `convohub-lead-form__error` and `convohub-lead-form__success`. The plugin does not store or print CSS written by you.

= Do leads need an email address? =

A lead needs an email address or a phone number. A phone number must include the country code, or you can set a default country code on the Leads tab.

= My site is behind a CDN or proxy and visitors get "too many submissions". =

The rate limit uses the visitor's IP address. Behind a proxy every visitor can look the same. Use the `convohub_client_ip` filter to return the real client IP from the header your proxy sets.

= Does the webhook work on a local or staging site? =

ConvoHub must be able to reach your site over the internet using HTTPS, so local addresses cannot receive events.

= What happens to my data when I uninstall the plugin? =

Deleting the plugin removes its settings, undelivered leads, scheduled retries and temporary data from your database. Data already sent to ConvoHub stays in your ConvoHub account.

== External services ==

This plugin connects your site to ConvoHub, a customer messaging service, at https://app.convohub.io. That address is fixed. Using this plugin requires a ConvoHub account.

**What is sent, and when**

* When you press Connect: the connection key you pasted is sent once to https://app.convohub.io, with your site's address and name and the WordPress and plugin versions. ConvoHub answers with the account and the access this site uses from then on. The key itself is not saved.
* When you test the connection, and when you use the Widget, Leads or Webhook settings: that access is sent to ConvoHub to read your account, inboxes and webhooks, and to create or update them.
* When a visitor loads a page with the chat widget: the visitor's browser loads the widget script from https://app.convohub.io and exchanges chat data with it. If customer identity verification is on, a signed-in customer's ID, name and email address, and a signature of the ID, are given to the widget.
* When a visitor submits the lead form: the name, email address, phone number, message, the page address and title, and campaign (UTM) parameters they provided are sent from your server to ConvoHub, and may be retried later if ConvoHub is unreachable.
* When the webhook is registered: ConvoHub sends event data (for example new customer messages) to your site's address.

This service is provided by ConvoHub (https://www.convohub.io). Terms of Service: https://www.convohub.io/terms. Privacy Policy: https://www.convohub.io/privacy.

== Privacy ==

The plugin adds suggested text to your site's privacy policy guide, and supports the WordPress personal data export and erase tools for form submissions that are waiting to be delivered. It sets a "convohub_logged_in" cookie for signed-in users and keeps the signed-in user's ID in the browser's local storage so the chat can detect a change of user. The chat widget loaded from ConvoHub sets its own cookies.

== Changelog ==

= 0.4.2 =
* The plugin always connects to https://app.convohub.io. The address is no longer a saved setting, so it cannot be changed in the database.

= 0.4.1 =
* The lead form's look is chosen with fields (button colour, corners, spacing, width) instead of a custom CSS box, as WordPress.org does not allow plugins to save arbitrary CSS. CSS saved by earlier versions is no longer used; it is shown once on the Leads tab so you can copy it into Additional CSS.
* The External services section links ConvoHub's Terms of Service and Privacy Policy.

= 0.4.0 =
* Connect with one key. In ConvoHub open Settings > Integrations > WordPress, generate a key and paste it on the Connection tab. The plugin always uses https://app.convohub.io, so there is no URL to type.
* The Connection tab shows the account, who connected it, when, and which key was used, and has a Disconnect button. A key works once and is never saved.
* Sites connected with an API access token keep working. The Connection tab asks you to replace the token with a key; the inbox, identity validation and webhook settings stay when the key is for the same account.
* The Help tab explains the key, every message a refused key can show, and Disconnect. Diagnostics report how the site is connected.

= 0.3.2 =
* A messaging call for emails that sets the subject and sends the HTML part, used by ConvoHub Commerce 0.7.2.

= 0.3.1 =
* Restyled admin screens: flat layout on the wp-admin page, sections with the title on the left, one status in the header, underline tabs, and the ConvoHub brand blue.
* Simpler Help tab: a search field and a list of topics.
* Shorter interface text, and one term ("identity validation") everywhere. No settings change.

= 0.3.0 =
* New Help tab: searchable guides, a setup guide, and diagnostics with "Copy for support".
* Redesigned admin screens: setup checklist, guided connection steps, clearer settings, a sticky save bar, and better keyboard, screen reader and phone support.
* Hooks for add-ons to contribute help articles and for sites to show documentation and support links.

= 0.2.0 =
* Configurable lead form fields.
* Messaging calls used by the ConvoHub Commerce add-on.

= 0.1.0 =
* First release: connection to ConvoHub, chat widget with display rules, verified customer identity, lead form block and shortcode with automatic retries, signed webhook receiver, and privacy tools.

== Upgrade Notice ==

= 0.4.2 =
The ConvoHub address is fixed to app.convohub.io. No action needed.

= 0.4.1 =
The custom CSS box on the Leads tab is gone. If you had saved CSS there, it is shown once on the Leads tab: copy it into WordPress's Additional CSS.

= 0.4.0 =
Connect with a key made in ConvoHub instead of an API token. Existing sites keep working, but should reconnect with a key: the Connection tab shows how. ConvoHub Commerce 0.7.2 works unchanged.

= 0.3.2 =
Required by ConvoHub Commerce 0.7.2. No settings change.

= 0.3.1 =
Restyled admin screens. No settings change. Required by ConvoHub Commerce 0.7.1.

= 0.3.0 =
New Help tab and redesigned admin screens. No settings change.

= 0.2.0 =
Required by ConvoHub Commerce 0.2.0 and newer.

= 0.1.0 =
First release.
