=== StudioMeta Voice AI ===
Contributors: studiometa, stdmeta
Donate link: https://studiometa.io/
Tags: chatbot, ai, live chat, appointment booking, voice assistant
Requires at least: 6.0
Tested up to: 7.1
Stable tag: 1.7.23
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI voice & chat receptionist for WordPress. Answers calls and chat 24/7, books real appointments, and reads your own site content.

== Description ==

**StudioMeta Voice AI** turns your WordPress site into a 24/7 AI receptionist — a real-time AI voice agent and AI chat widget that answers visitors by voice or text, books real appointments on your calendar, and only hands off to a human when it should.

Unlike a scripted chatbot, StudioMeta reads your own site content, docs and pages to build its knowledge base automatically — so it answers from what you've actually published, not a canned script.

**Every install includes a free trial — no signup, no credit card required.** Click "Start Free Trial" in the admin panel to activate 30 voice minutes and 100 chat messages before deciding on a paid plan.

= Why an AI voice agent, not just another chat widget? =

* **Answers by real-time voice, not just text** — most WordPress chatbot plugins only type back; your visitors can actually talk to this one, like a phone call, right in the browser
* **Books real appointments** — checks your working hours and books open calendar slots on the spot, no calendar tool or webhook required
* **Trained on your own content** — point it at your site, docs or PDFs and it builds a knowledge base in one click
* **No API key to manage** — the AI runs on our hosted infrastructure, so there's nothing to sign up for or configure outside this plugin
* **No coding required** — install, click Start Free Trial, and the widget is live
* **Try before you buy** — 30 voice minutes and 100 chat messages, no credit card

= Key features =

* **AI voice agent** — visitors talk to your AI agent, the agent talks back (real-time, streaming) — like a phone call to your front desk
* **AI live chat** — the same agent in a classic chat widget, for visitors who prefer typing
* **Appointment booking** — checks your working hours and books real calendar slots during the conversation
* **Google Calendar sync** — connect in one click, no API key; busy times stay off what visitors are offered
* **Multi-language** — English, Persian (فارسی), Arabic, French, Spanish, and more, auto-detected per visitor
* **Knowledge base import** — auto-crawl your site to train the agent on your content
* **Customizable widget** — color, position (bottom-left/right), style (FAB or pill), six ready themes
* **Gutenberg block** — drag a "Voice AI Widget" block into any page or post to place the widget inline, no shortcode needed
* **Suggested questions** — chips that prompt visitors with common questions
* **Agent customization** — name, voice, response style, system prompt, timezone
* **CRM integration** — connect your own HubSpot account and every call and chat logs as a contact with notes
* **Custom tools & automation** — connect your agent to any automation platform (n8n, Make, Zapier) via a webhook you provide
* **Usage dashboard** — see voice minutes used, sessions, and remaining quota
* **Smart fallback** — when one quota is exhausted, the other stays available

= Built for =

* Healthcare & dental clinics — books appointments, screens intake questions
* Real estate agencies — qualifies leads, schedules showings
* Law firms — takes after-hours intake through the site
* Restaurants — handles reservations and hours questions
* Automotive shops — books service slots, answers inventory questions
* Salons & spas — fills last-minute cancellations
* Ecommerce stores — answers order and shipping questions
* Any small business that doesn't want to miss another website inquiry

= How the trial works =

1. Activate the plugin, then click **Start Free Trial** in the admin panel
2. Use 30 voice minutes and 100 chat messages on real visitor conversations
3. When the voice quota is exhausted, the chat widget keeps working (and vice versa)
4. When both are exhausted, the widget shows an upgrade button linking to our pricing page

= Upgrading to a paid plan =

If you want unlimited or higher quotas, visit [studiometa.io/pricing](https://studiometa.io/pricing/). After purchase, your widget reactivates automatically within 5 minutes — no need to copy and paste a license key.

== External services ==

**This plugin connects to external services provided by StudioMeta to function.** This is required because the plugin is an interface to a hosted AI assistant. The following services are used:

= 1. StudioMeta Voice AI API (api2.studiometa.io) =

**What it does:** Hosts the AI agent. Handles license validation, quota tracking, knowledge base storage, agent configuration, voice/chat session orchestration, and dashboard analytics.

**When it is contacted:**

* On plugin activation: to issue a free trial license (sends site URL, admin email, business name, site fingerprint, WordPress version, plugin version, language preference)
* When you save settings or agent configuration: to sync your changes to the hosted agent
* When you click "Import KB from Website": to crawl your public pages and build a knowledge base
* When you click "Optimize with AI": to improve your system prompt
* When the admin Dashboard loads: to fetch usage statistics
* Every 5 minutes (cached): to check current quota status (decides whether the widget shows voice, chat, both, or an upgrade button)
* When a visitor uses the voice or chat widget: a WebSocket connection is opened to `wss://api2.studiometa.io/voice` to stream audio and messages

**Data sent:** site URL, admin email, business name, business phone number (only if you enter one), your custom agent configuration (name, voice, system prompt, knowledge base text, suggested questions, custom tools), and during sessions: visitor audio and chat messages (processed only for the duration of the conversation).

**Data NOT sent:** WordPress user passwords, post content (unless you explicitly import it via "Import KB"), visitor IP addresses, visitor names or accounts.

* Service homepage: [https://studiometa.io](https://studiometa.io)
* Terms of Service: [https://studiometa.io/terms/](https://studiometa.io/terms/)
* Privacy Policy: [https://studiometa.io/privacy-policy-2/](https://studiometa.io/privacy-policy-2/)

= 2. StudioMeta Workflow Webhooks (n8n.studiometa.io) =

**What it does:** Sends transactional emails (welcome email on activation, license key email after purchase, usage alerts at 80% and 100%, monthly usage report).

**When it is contacted:**

* Once on plugin activation: to trigger the welcome email
* When usage thresholds are crossed (server-side): to trigger usage alert emails

**Data sent:** admin email, site URL, business name, current plan, usage percentages.

* Service homepage: [https://studiometa.io](https://studiometa.io)
* Terms of Service: [https://studiometa.io/terms/](https://studiometa.io/terms/)
* Privacy Policy: [https://studiometa.io/privacy-policy-2/](https://studiometa.io/privacy-policy-2/)

= 3. HubSpot (api.hubapi.com) — optional, only if you connect it =

**What it does:** Syncs leads captured by the voice/chat widget (name, email, phone, notes) into your own HubSpot CRM as contacts.

**When it is contacted:** Only if you explicitly connect HubSpot under **Voice AI → Integrations** by entering your own HubSpot Private App Token. If you never connect it, the plugin never contacts HubSpot.

* When you click "Connect": one test request to `api.hubapi.com` to verify your token
* When the widget captures a lead: the lead's name, email, phone, and notes are sent to `api.hubapi.com` to create/update a contact in **your** HubSpot account

**Data sent:** your HubSpot Private App Token (stored in your WordPress database, sent only to HubSpot), and captured lead fields (name, email, phone, notes).

* Service homepage: [https://www.hubspot.com](https://www.hubspot.com)
* Terms of Service: [https://legal.hubspot.com/terms-of-service](https://legal.hubspot.com/terms-of-service)
* Privacy Policy: [https://legal.hubspot.com/privacy-policy](https://legal.hubspot.com/privacy-policy)

= 4. Google Gemini Live (indirectly, via api2.studiometa.io) =

The AI capabilities are powered by Google's Gemini Live API. The plugin does **not** contact Google directly — all requests go through `api2.studiometa.io`, which forwards them to Google. You do not need a Google account or API key.

* Google Gemini Terms: [https://ai.google.dev/terms](https://ai.google.dev/terms)
* Google Privacy Policy: [https://policies.google.com/privacy](https://policies.google.com/privacy)

= 5. OpenAI Realtime (indirectly, via api2.studiometa.io) =

On the Premium and Enterprise plans, voice conversations are powered by OpenAI's Realtime API instead. The plugin does **not** contact OpenAI directly — all requests go through `api2.studiometa.io`, which forwards them to OpenAI. You do not need an OpenAI account or API key. Plans other than Premium and Enterprise do not use this service.

**Data sent:** the visitor's microphone audio and typed messages during a voice conversation, plus your configured agent name, greeting, system prompt and knowledge base.

* OpenAI Terms of Use: [https://openai.com/policies/terms-of-use](https://openai.com/policies/terms-of-use)
* OpenAI Privacy Policy: [https://openai.com/policies/privacy-policy](https://openai.com/policies/privacy-policy)

= 6. Google Calendar (calendar.googleapis.com) — optional, only if you connect it =

**What it does:** Lets the AI agent book real appointments during a conversation. Reads busy times from your connected Google Calendar so the agent never offers a slot you're already booked, and creates a calendar event when a visitor books.

**When it is contacted:** Only if you explicitly connect Google Calendar under **Voice AI → Appointments** by clicking "Connect Google Calendar" and signing in through Google's own consent screen. If you never connect it, the plugin never contacts Google Calendar, and appointment booking still works from the working hours you set — it simply won't check your calendar for conflicts.

* When you connect: a one-time OAuth sign-in with Google, requesting only free/busy visibility and the ability to create/edit events it creates — never your full calendar or any other Google data
* When a visitor asks about availability: your calendar's busy times are checked (cached briefly) to avoid offering a taken slot
* When a visitor books: an event is created on your calendar with the appointment details

**Data sent:** an encrypted access credential (stored on StudioMeta's servers, never in your WordPress database), and appointment details (visitor name, email, and time) when creating a calendar event.

**Data NOT sent:** the content of your other calendar events, contacts, or any other Google account data.

You can disconnect at any time from **Voice AI → Appointments**, or by revoking access directly from your Google Account permissions page.

* Google Calendar Terms: [https://developers.google.com/terms](https://developers.google.com/terms)
* Google Privacy Policy: [https://policies.google.com/privacy](https://policies.google.com/privacy)

= 7. Twilio (api.twilio.com) — optional, only if you connect it =

**What it does:** Lets real phone calls to a phone number you own be answered by your AI agent, using **your own Twilio account**. You keep your own Twilio account, buy your own number, and pay Twilio directly for call minutes and number rental — StudioMeta does not resell or bill you for Twilio usage. Talk time on answered calls counts against the same monthly voice minutes as the website widget.

**When it is contacted:** Only if you explicitly connect a Twilio account under **Voice AI → Integrations** by entering your Twilio Account SID, Auth Token, and phone number. If you never connect it, the plugin never contacts Twilio.

* When you connect: your Account SID and Auth Token are verified once against Twilio to confirm they are valid before being saved
* When someone calls your connected number: Twilio sends the call to StudioMeta's servers, and the caller's audio and the agent's replies are streamed for the duration of the call

**Data sent:** your Twilio Account SID and Auth Token (stored encrypted on StudioMeta's servers, never in your WordPress database), the phone number you connected, and during calls: the caller's audio (processed only for the duration of the conversation).

**Data NOT sent:** your Twilio billing details, SMS messages, call recordings held in your Twilio account, or any other data from your Twilio account.

You can disconnect at any time from **Voice AI → Integrations**, or by removing the webhook from your number in the Twilio Console.

* Twilio Terms of Service: [https://www.twilio.com/legal/tos](https://www.twilio.com/legal/tos)
* Twilio Privacy Policy: [https://www.twilio.com/legal/privacy](https://www.twilio.com/legal/privacy)

= How to opt out =

If you do not want the plugin to contact these services, simply deactivate and uninstall the plugin. The plugin cannot function without the hosted services because the AI assistant runs on our infrastructure (similar to how an Akismet plugin needs the Akismet service, or a Mailchimp plugin needs Mailchimp).

== Installation ==

1. Upload the `studiometa-voice-ai` folder to `/wp-content/plugins/`, OR install through the WordPress plugin browser
2. Activate the plugin through the **Plugins** menu in WordPress
3. Click **Start Free Trial** in the admin notice to activate your free trial — you'll see the **Voice AI** menu item in your WordPress admin sidebar
4. Click **Voice AI → My Agent** to customize your assistant's name, voice, and knowledge base
5. The widget appears as a floating button on every page of your site — or place it inline with the **Voice AI Widget** block in the block editor, or the shortcode `[smva_widget]`

== Frequently Asked Questions ==

= Do I need to create an account? =

No. Click **Start Free Trial** in the admin panel after activation. No account or credit card needed.

= Is StudioMeta Voice AI free? =

Every install starts with a free trial (30 voice minutes + 100 chat messages, no credit card). After the trial, you can upgrade for more usage, or keep using whichever quota — voice or chat — hasn't run out yet.

= Do I need coding skills to set this up? =

No. Install the plugin, click Start Free Trial, and the widget appears automatically. Customizing your agent's name, voice, and knowledge base is done through simple admin screens — no code, no API keys.

= Will this slow down my site? =

The widget script loads in the footer after your page content, so it doesn't block your site from rendering.

= Which AI powers the assistant, and do I need my own API key? =

The assistant runs entirely on StudioMeta's hosted AI Engine. You don't need your own API key or a separate AI subscription — everything is included in the plugin.

= What happens when my trial runs out? =

The widget shows an upgrade button linking to our pricing page. If you've used all your voice minutes but still have chat messages, the widget shows only the chat tab (and vice versa).

= Will the widget reactivate automatically after I purchase? =

Yes. Within 5 minutes of your purchase, the plugin detects the upgrade and the widget switches back to full mode. You don't need to copy and paste a license key.

= Can I customize the voice and personality of the agent? =

Yes. Go to **Voice AI → My Agent** to set the agent's name, voice (multiple voices available), response style (concise / balanced / detailed), system prompt, and knowledge base.

= What languages does the assistant speak? =

English, Persian (فارسی), Arabic, French, Spanish, and more. Set the language under **Voice AI → General**.

= Can I add the widget to specific pages only? =

Yes. By default the widget appears site-wide. You can disable that and use the shortcode `[smva_widget]`, or the **Voice AI Widget** Gutenberg block, to place it manually on selected pages.

= Is there a Gutenberg block? =

Yes. Search for "Voice AI Widget" in the block inserter and drag it into any page or post to place the widget at that exact spot — no shortcode needed. It works the same as the `[smva_widget]` shortcode.

= Does this work on mobile? =

Yes. The widget is fully responsive and supports voice on mobile browsers that allow microphone access (most modern browsers do).

= Does the plugin send data anywhere? =

Yes. Because the AI runs on our hosted infrastructure (api2.studiometa.io), the plugin sends configuration data and conversation contents to our servers. See the **External Services** section above for full details.

= Is uninstalling the plugin clean? =

Yes. When you uninstall, the plugin removes all its options, transients, and licensing data from your WordPress database.

= Where can I get support? =

Visit [studiometa.io/contact](https://studiometa.io/contact/) or use the support forum on this plugin's WordPress.org page.

== Screenshots ==

1. Chat widget on a live site showing clickable contact cards
2. Voice call in progress — real-time voice conversation with AI agent
3. Admin dashboard — usage stats, session history, and quota tracking
4. Agent customization — knowledge base import, system prompt, and suggested questions
5. Widget appearance — six visual themes to match your brand
6. Voice AI Widget block — place the widget at an exact spot on a page from the block inserter

== Third-Party Assets ==

Vazirmatn v33.003 by Saber Rastikerdar, used for Persian and Arabic text.
Licensed under the SIL Open Font License 1.1 (see assets/fonts/OFL.txt) and
distributed unmodified. Only the Non-Latin subset is bundled, and it is served
from this plugin folder -- no font CDN is contacted, so no visitor or
administrator IP address is sent to a third party.
Source: https://github.com/rastikerdar/vazirmatn

== Source Code ==

The full source code of this plugin, including the unminified version of widget.js and all build tools, is publicly available on GitHub:

https://github.com/Pejvak2001/studiometa-voice-ai

== Changelog ==

= 1.7.23 =
* Fixed: the admin notices could not be dismissed anywhere except the plugin's own pages. On the Dashboard and every other screen, "I already did" did nothing and closing the notice only hid it until the next page load, so it kept coming back. Closing or answering a notice now always sticks, wherever you are in wp-admin.

= 1.7.22 =
* Fixed: a connected HubSpot account no longer collects duplicate contacts. A visitor who typed their name, phone and email while talking to the assistant could end up as three separate contacts, two of them nearly empty. Name and phone now reach HubSpot only as part of the complete lead record.

= 1.7.21 =
* Privacy: uninstalling the plugin now removes all stored data, including captured leads and any connected HubSpot token. Only your license credentials are kept so a reinstall restores your plan.
* Performance: the widget script now loads deferred, and the front end no longer makes a blocking network call while a page renders — quota is read from cache and refreshed in the background.
* Accessibility: the assistant panel and transcript now expose dialog and live-region roles for screen readers.
* Fixed: bundled translations (e.g. Persian) now load correctly, and removed an unused internal event hook.
* Hardening: additional server-side input limits and safer error handling.

= 1.7.20 =
* Improved security: the widget no longer places long-lived credentials in page HTML. It now requests a short-lived, single-site access token at the moment a conversation starts, so nothing reusable is exposed to visitors or other scripts on the page.
* Improved: voice and chat sessions are now tied to the site they were issued for, and admin requests for transcripts and recordings send their credentials in headers rather than the URL.
* Hardened: assorted server-side checks around license activation and knowledge-base website crawling.

= 1.7.19 =
* Fixed: a phone number shown on screen in a right-to-left conversation (e.g. Persian, Arabic) could display with the "+" moved to the end, making a correct number look wrong at a glance. The stored and spoken number was never affected — only how it was written on screen. Numbers, email addresses and links now always display left-to-right regardless of the conversation's language.

= 1.7.18 =
* Added: a Business Phone field in Settings. This is the only number your assistant will ever give a visitor, and it is worth filling in even if the number already appears in your knowledge base.
* Fixed: the assistant could invent a phone number when asked how to reach you. If it had no number on file it would sometimes supply a plausible-looking one rather than say it had none — sending visitors to a stranger. It now states the number you entered, or says plainly that there is no phone number, and a number that is not yours is blocked from appearing on screen at all.
* Fixed: internal wording from the assistant's own tools could occasionally appear in the middle of a reply. Replies are now cleaned before they reach the visitor.
* Improved: the same no-invented-details rules now apply to text chat, which had been relying on the assistant's judgement alone.

For releases before 1.7.18, see [changelog.txt](https://plugins.svn.wordpress.org/studiometa-voice-ai/trunk/changelog.txt) in the plugin folder.

== Upgrade Notice ==

= 1.7.23 =
Fixes admin notices that could not be permanently dismissed outside the plugin's own pages — closing one only hid it until the next page load. Recommended for all users.

= 1.7.22 =
Fixes a connected HubSpot account collecting duplicate, half-empty contacts for a single visitor. Recommended if you use the HubSpot integration.

= 1.7.21 =
Privacy and performance release. Uninstalling now removes all stored data including captured leads, the widget script no longer blocks page rendering, and the assistant is more usable with a screen reader. Recommended for all users.

= 1.7.20 =
Security release. The widget no longer places long-lived credentials in your page HTML — it now requests a short-lived, single-site token when a conversation starts. Recommended for all users.

= 1.7.19 =
Fixes a phone number sometimes displaying with the "+" in the wrong place in a right-to-left conversation (Persian, Arabic). Cosmetic only — recommended for anyone using a right-to-left language.

= 1.7.18 =
Fixes the assistant occasionally inventing a phone number when asked how to reach you. Recommended for all users. After upgrading, set your number in Settings → Business Phone, or leave it empty if you have none.

= 1.2.0 =
Per-site agent isolation. If you have used the same license on multiple sites, please review your active site after upgrade.

= 1.1.1 =
Critical fix: text fields no longer accumulate backslashes on save. Recommended for all users.

= 1.1.0 =
Adds free trial, smart quota fallback, and auto-upgrade. Recommended for all users.
