WooCommerce Voice AI — AI Voice Agent for WordPress & WooCommerce | Telenow

Turn WooCommerce store events into automated AI phone calls — recover abandoned carts, confirm COD orders to cut RTO, send delivery updates, win back lapsed customers, and call new leads back instantly — with every call outcome written back onto the order.

Telenow Voice AI is a free, open-source WordPress / WooCommerce voice AI plugin that connects your store to the Telenow voice-AI calling service, so a natural-sounding AI voice agent phones your shoppers automatically on key store events. It powers abandoned cart recovery, COD confirmation for RTO reduction, order confirmation calls, delivery updates, win-back re-engagement, and instant lead callbacks — and because the agent is multilingual (English, Hindi, other Indian languages, plus global voices) it can talk to customers in their own language. You bring your own Telenow account and vai_live_… API key (calls are billed on usage by Telenow); the plugin itself is free. Each store event becomes an AI phone call, and the outcome is written back onto the WooCommerce order as an order note plus meta — so abandoned-cart, COD, and delivery results live right where you manage orders.

Table of Contents

• Features
• Installation
• Configuration
• Telenow API surface
• Layout
• Extensibility (filters / actions)
• Design notes / assumptions
• About Telenow
• License

✨ Features

Every automation is independently toggled and has its own Telenow agent, delay, quiet hours, and filters.

• 🛒 Abandoned cart / checkout recovery (voice AI). WooCommerce has no native server-side cart-abandon event, so a checkout that never reaches a paid status (pending / failed / checkout-draft) is the signal. A 15-minute cron scan calls those unpaid orders once they pass your configured delay, passing the recovery pay link and an optional discount code — automated abandoned cart recovery by phone, not just email.
• 📦 COD confirmation & RTO reduction. Confirms Cash-on-Delivery orders before you ship them, firing on thankyou / new_order (it also catches admin- and API-created orders). A "confirmed" outcome sets _telenow_cod = confirmed and can auto-advance the order to Processing ; a "refused" outcome sets _telenow_cod = cancelled and tags the order — so you stop shipping orders headed for return-to-origin and cut RTO.
• 🚚 Order confirmation & delivery updates. Fires on the woocommerce_order_status_changed transitions you choose (e.g. processing, completed), passing tracking number / URL / carrier on a best-effort basis from the common shipment-tracking plugins.
• 💬 Win-back / re-engagement. A daily cron scan finds customers whose most recent order is older than N days and calls them with an optional win-back offer.
• ⭐ Reviews / NPS (scaffolding). Settings and the daily-scan hook are in place for a post-delivery feedback/NPS call (stub — not yet active).
• 📞 Lead forms — instant AI callback (speed-to-lead). Beyond orders, the plugin can place an instant AI voice callback the moment a visitor submits a contact/lead form. It captures the lead and every submitted field into its own Telenow Leads dashboard and dials the phone on the form. Supported form plugins (each hooked only when active): Contact Form 7, WPForms, Gravity Forms, Ninja Forms, Elementor Pro Forms, Fluent Forms, Formidable Forms. The phone field is auto-detected (phone/mobile/tel/whatsapp/contact/number), with a per-phone dedupe window so a double-submit never double-calls.
• 📥 Telenow Leads dashboard. A read-only, paginated admin list (newest first) of every captured submission — source form, name, masked phone, call status, disposition, and a trimmed summary — backed by a custom {prefix}telenow_leads table.
• 🔁 Outcome write-back (orders & leads). On save of a valid API key the plugin auto-subscribes Telenow's call.ended + call.analyzed webhooks, stores the signing secret, and on every delivery writes the result back: an order note + meta (_telenow_last_status, _telenow_disposition, COD mapping, …) for store-event calls, or the matching row update for lead-form callbacks.
• 🔐 HMAC signature verification. Every inbound webhook must carry a valid X-VoiceAI-Signature (HMAC-SHA256 over the raw body), compared in constant time; events that fail are rejected with HTTP 401, and a subscription is only stored if it returned a signing secret.
• 🌐 Multilingual voice. Your Telenow agent can speak English, Hindi, other Indian languages, and global voices — order totals and item summaries are passed as plain, speakable strings so they read cleanly.
• 🌙 Quiet hours. A store-timezone window (overnight ranges supported) during which no calls are placed; cron automations simply retry on the next scan outside the window.
• 🧩 HPOS compatible. Uses the WooCommerce CRUD order API throughout and declares custom_order_tables (High-Performance Order Storage) compatibility.
• 🧰 Extensive filters & actions. A dozen hooks let you suppress specific calls, mutate the context variables, tune phone handling and quiet hours, source tracking from any plugin, customize COD disposition vocabulary, and run custom logic (CRM sync, tags) after an outcome is applied.
• 🔑 Secret-safe by design. The API key is never echoed (the field shows a vai_live_••••1234 mask and keeps the saved key when left masked) and never logged (the logger redacts vai_(live|test)_…).

🚀 Installation

Option A — Production install (WordPress admin)

1. Download or clone this repository and zip the plugin folder so the archive contains telenow-voice.php at the top level. (When you clone, the folder is named Voice-AI-Wordpress-Plugin — you can keep that name or rename it to woocommerce-telenow.)
2. In wp-admin → Plugins → Add New → Upload Plugin, upload the zip and click Install Now, or drop the unzipped folder straight into wp-content/plugins/.
3. Click Activate. (WooCommerce must be installed and active — the plugin shows an admin notice and stays inactive otherwise.)

Option B — Developer install (git)

# From your WordPress install's plugins directory:
cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/TelenowAI/Voice-AI-Wordpress-Plugin.git
wp plugin activate Voice-AI-Wordpress-Plugin      # or activate via wp-admin → Plugins

Then connect Telenow

1. Go to WooCommerce → Telenow Voice AI.
2. Paste your Telenow API key (create one in the Telenow dashboard under Developers → API Keys; keys look like vai_live_…) and click Save changes. The plugin validates the key against the Telenow API and auto-subscribes the call-result webhook.
3. Enable the automations you want, paste the Telenow Agent ID (UUID) for each, and set delays / quiet hours. To use instant lead callbacks, enable Lead forms and set a callback agent.

HTTPS required. Your site must be reachable over HTTPS for Telenow to deliver call-result webhooks. For local development, expose the site with a tunnel such as ngrok and point the API base / receiver at the public URL.

⚙️ Configuration

All settings live under WooCommerce → Telenow Voice AI:

• Connection — API key, API base URL (override only for self-hosted / regional Telenow deployments), default country code (prepended to national numbers, e.g. +91), and the spoken store name.
• Quiet hours — a from/to window in the store timezone (supports overnight ranges; leave blank to disable).
• Per-automation — enable toggle, Telenow Agent ID (UUID), and the relevant timing/offer fields (cart delay & max age + discount, COD auto-processing, watched order statuses, win-back inactivity threshold + discount, review days, lead-form callback agent + extra phone field names + dedupe window).
• Webhook status — shows the receiver URL and subscription state, with Re-subscribe and Unsubscribe buttons.

🧩 Telenow API surface

Purpose	Request
Validate key	GET /api/v1/me
Place call	POST /api/sessions/initiate-call ({ agentId, mobileNumber, variables, identifier, machineDetection }; response enveloped under data)
Subscribe webhook	POST /api/v1/hooks (source: "woocommerce", events: [call.ended, call.analyzed], includeTranscript: true)
List / remove	GET /api/v1/hooks?source=woocommerce, DELETE /api/v1/hooks/:id
Inbound (this plugin)	POST {site}/wp-json/telenow/v1/event

Authentication is a single header — X-API-Key: vai_live_… — on every request. The base URL defaults to https://api.telenow.ai; override it in settings or via the telenow_voice_api_base filter for self-hosted / regional deployments.

🧱 Layout

telenow-voice.php                      main file: header, constants, bootstrap, activation (cron + flush)
uninstall.php                          remove remote hook + options + leads table on delete
includes/
  helpers.php                          settings access, E.164 normalize, quiet-hours, redacting logger
  class-telenow-client.php             API client (me / initiate_call / *_hook) over wp_remote_*
  class-telenow-settings.php           WooCommerce-menu settings page (nonces, sanitize, validate + subscribe)
  class-telenow-automations.php        WC event handlers → build variables → place call → map session → order
  class-telenow-webhook.php            REST route telenow/v1/event; raw-body HMAC verify; outcome write-back
  class-telenow-cron.php               telenow_scan_abandoned (15m) + telenow_scan_winback (daily)
  class-telenow-leads.php              {prefix}telenow_leads table + read-only "Telenow Leads" admin list
  class-telenow-forms.php              lead-form adapters (CF7/WPForms/Gravity/Ninja/Elementor/Fluent/Formidable) → instant callback
assets/admin.css                       minimal admin styling

🔌 Extensibility (filters / actions)

Hook	What it does
telenow_voice_api_base	Override the API base URL.
telenow_voice_should_call ( $allow, $order, $automation, $vars )	Suppress a specific order call — return false.
telenow_voice_call_variables ( $vars, $order, $automation )	Mutate the context variables before dialing.
telenow_voice_normalize_phone / telenow_voice_reject_phone	Tune phone handling.
telenow_voice_in_quiet_hours	Override the quiet-hours decision.
telenow_voice_abandoned_statuses	Which statuses count as abandoned.
telenow_voice_tracking_info ( $info, $order )	Supply tracking number/url/carrier for unsupported plugins.
telenow_voice_cod_move_to_processing / telenow_voice_cod_auto_cancel	COD outcome side-effects.
telenow_voice_cod_confirmed_words / telenow_voice_cod_refused_words	Disposition vocabulary.
telenow_voice_event_applied ( $order, $event_type, $payload )	Run custom logic after an order event is applied (CRM sync, tags).
telenow_voice_lead_should_call ( $allow, $lead_id, $source, $fields )	Suppress a specific lead-form callback — return false.
telenow_voice_lead_call_variables ( $vars, $lead_id, $source, $fields )	Mutate lead-callback variables before dialing.
telenow_voice_lead_event_applied ( $lead_id, $event_type, $payload )	Run custom logic after a lead-callback outcome is applied.

🛠️ Design notes / assumptions

• Abandoned-cart detection is pragmatic: WooCommerce has no server-side cart-abandon event, so an order created at checkout that never reaches a paid status is the signal. woocommerce_checkout_order_processed stamps a candidate timestamp; the 15-minute cron (telenow_scan_abandoned) calls candidates older than the configured delay, capped by a max-age so stale drafts aren't chased. Dedupe + an is_paid() re-check guard against double/late calls.
• Tracking number sourcing is best-effort across the common shipment-tracking plugins — official WooCommerce Shipment Tracking (_tracking_number, _tracking_provider, _custom_tracking_link), Advanced Shipment Tracking / AST (_wc_shipment_tracking_items), and generic _tracking_number / _tracking_url / _tracking_carrier — with telenow_voice_tracking_info as the escape hatch.
• Signature verification is done over the raw request body. Telenow's official server SDK uses a sha256=<hex> digest; the spec also references base64. To stay robust the receiver accepts either hex or base64, compared in constant time (hash_equals). A subscription is only stored if it returned a signing secret, so unverifiable events are never accepted.
• Mapping back prefers the persisted sessionId → order_id map (written at call time, capped at 500 entries); the identifier (the WC order id, or lead:<id> for lead callbacks) we send is the fallback.
• Lead capture is non-destructive: every supported submission is stored in the Telenow Leads table even when no call is placed (no phone, no agent configured, quiet hours, or a dedupe hit), so all the data still lands in the dashboard. Each form-plugin hook is wrapped so an absent or misbehaving provider can never fatal the submission flow.
• Secrets: the API key is never echoed (the settings field shows a vai_live_••••1234 mask and keeps the saved key when left masked) or logged (the logger redacts vai_(live|test)_…). The signing secret lives in its own option.
• HPOS: uses the CRUD order API throughout and declares custom_order_tables compatibility.
• Clean uninstall: deleting the plugin best-effort removes the remote webhook subscription, all plugin options, and the leads table; order meta (notes/disposition) is intentionally left in place so historical call outcomes survive.

📞 About Telenow

Telenow is an AI voice-calling platform for building natural-sounding, multilingual AI voice agents that place and receive real phone calls — for sales, support, confirmations, reminders, and lead follow-up. This plugin is the official WooCommerce connector: you keep your agents and number on Telenow, and the plugin wires them to your store's events and writes results back onto your orders. Learn more at telenow.ai, read the documentation, or see pricing.

📄 License

Released under the GPL-2.0-or-later license — see the plugin header in telenow-voice.php and https://www.gnu.org/licenses/gpl-2.0.html. © Telenow AI.