=== Harkbell Voice Receptionist ===
Contributors: harkbell
Tags: ai receptionist, voice assistant, booking, appointments, customer service
Requires at least: 6.3
Tested up to: 7.1
Stable tag: 1.0.1
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Put your Harkbell AI receptionist on your site: visitors press a button and talk, get real answers, and book, instead of filling in a form.

== Description ==

Harkbell is an AI receptionist for small businesses. It answers questions about your services, prices and opening hours, takes bookings and callback requests, and files every conversation in your Harkbell dashboard.

This plugin puts your Harkbell receptionist's talk button on your WordPress site. A visitor presses it, allows the microphone, and talks to your receptionist out loud instead of filling in a contact form.

* One key. Copy it from your Harkbell dashboard and paste it under Settings → Harkbell. Pasting the whole embed code works too: only the key is kept.
* Choose the pages. Show the button everywhere, only on the pages you tick, or everywhere except them.
* The same talk button as Harkbell's one-line snippet, loaded asynchronously in the footer so it never holds up your page.
* The plugin stores only the key and your page choices. No tracking, and no credit link.
* Nothing loads and nothing is sent anywhere until a key is saved.

A Harkbell account is required. There is a free plan, and you can create an account at [harkbell.com](https://harkbell.com).

The talk button's script is served unminified from harkbell.com.

== Installation ==

1. Install and activate the plugin, from Plugins → Add New Plugin, or by uploading the zip under Plugins → Add New Plugin → Upload Plugin.
2. In Harkbell, publish your agent, open Configuration → Widget and copy the WordPress plugin key.
3. In WordPress, open Settings → Harkbell, paste the key and save. The page tells you whether Harkbell accepts this site.
4. If your Allowed domains list in Harkbell is not empty, add your site's domain to it and republish.

== Frequently Asked Questions ==

= Do I need a Harkbell account? =

Yes. The plugin shows your own Harkbell receptionist, so it needs a Harkbell account with a published agent. There is a free plan at [harkbell.com](https://harkbell.com).

= Where do I find my key? =

In your Harkbell dashboard, open Configuration → Widget and copy the WordPress plugin key. It starts with emb_. Pasting the whole embed code from the same page works too.

= The talk button does not appear =

Work through these in order.

* Allowed domains. If the Allowed domains list under Configuration → Widget in Harkbell is not empty, it has to include your site's domain. Add it, or empty the list, then republish. Then press Check connection under Settings → Harkbell.
* Caching and speed plugins. Plugins that delay, combine or minify JavaScript can stop the button from starting. Exclude harkbell-widget.js from them: WP Rocket's "Delay JavaScript execution", LiteSpeed Cache's "JS Combine" and "Load JS Deferred", Autoptimize's "Aggregate JS-files", and Cloudflare Rocket Loader. The plugin already marks its script tag so that most of them leave it alone.
* The snippet pasted in your theme as well. If the Harkbell embed code was added to your theme or a header and footer plugin before, remove it. Two copies mean two buttons.

= Visitors are told the microphone is blocked =

Some security plugins and hosts send a Permissions-Policy header of microphone=(), which blocks the microphone on every page. Change it to allow microphone=(self).

If your site sends a Content-Security-Policy, it has to allow script-src https://harkbell.com and connect-src https://voice.harkbell.com wss://voice.harkbell.com.

= Can I show it on some pages only? =

Yes. Under Settings → Harkbell, choose "Only the pages ticked below" or "Every page except the ones ticked below", then tick your home page and the pages you want. Posts, products and anything else that is not a page can be added by ID.

Developers can also decide per request with the harkbell_widget_enabled filter. It runs only once a key is saved and the button is switched on, so it can hide the button but never show it without a key:

`add_filter( 'harkbell_widget_enabled', function ( $load ) { return $load && ! is_page( 'checkout' ); } );`

= Does it slow my site down? =

The plugin adds one script tag to the pages you choose, and nothing else. That script loads asynchronously in the footer, so your pages render without waiting for it. The voice connection and the microphone only start when a visitor presses the button.

== External services ==

This plugin relies on Harkbell (https://harkbell.com), a hosted AI voice receptionist. It does nothing until a site administrator saves a Harkbell key under Settings → Harkbell.

1. On each front-end page where you have set the button to appear, the visitor's browser loads https://harkbell.com/embed/harkbell-widget.js. The request carries your Harkbell key and, like any web request, the visitor's IP address, user agent and the address of the page. The script then fetches the button's settings from voice.harkbell.com.
2. Only when a visitor presses the button and allows the microphone, their voice and the conversation are sent to voice.harkbell.com to be answered. Harkbell keeps the audio and a transcript for your account.
3. When you save a new key, or press Check connection, your server sends the key and your site's address to voice.harkbell.com to confirm the key is accepted.

Harkbell's Terms of Service: https://harkbell.com/terms
Harkbell's Privacy Policy: https://harkbell.com/privacy

The talk button also uses Google's public STUN server, stun.l.google.com. Only when a visitor presses the button and allows the microphone, their browser asks that server for the public address of their network, which a voice call in the browser uses to reach voice.harkbell.com. The request carries the visitor's IP address and nothing from the conversation.

Google's Terms of Service: https://policies.google.com/terms
Google's Privacy Policy: https://policies.google.com/privacy

== Changelog ==

= 1.0.1 =
* Deleting the plugin on a multisite network removes its key and last connection check from every site, not only the main one.
* The suggested privacy-policy text, and External services here, name Google's public STUN server, which the talk button asks for the visitor's network address when a call starts.

= 1.0.0 =
* First release.
