Crossmedia Helpdesk

[Currently in closed testing]

A single-tenant WhatsApp helpdesk for WordPress. Run your own multi-agent support inbox on the WhatsApp Cloud API — with role-based access, media handling, an optional AI assistant, and configurable data retention. Any WordPress install can drop it in and operate its own helpdesk; one operator can serve many of their own clients through a single WhatsApp number.

  • Version: 1.0
  • Requires: WordPress 5.8+, PHP 7.4+
  • Author: Gino Croes (Crossmedia297) — https://crossmedia297.com
  • Support: admin@crossmedia297.com
  • License: GPL-2.0-or-later

Features

  • WhatsApp Cloud API inbox — receive and reply to WhatsApp messages from a shared agent inbox inside wp-admin.
  • Team inbox with roles — Administrator, Manager, and Agent roles with scoped visibility and actions.
  • Conversation lifecycle — open / pending / closed status, assignment, and reassignment.
  • 24-hour window handling — free-text replies inside WhatsApp’s service window; the composer switches to approved templates once it closes.
  • Media — inbound images, audio/voice, video, documents and stickers are downloaded to protected storage and served only to authorised staff.
  • Notifications — email to the assigned agent (or managers) plus in-dashboard browser notifications and an unread badge.
  • Optional AI assistant — auto-answers new conversations from a knowledge base and escalates to a human when needed (see below).
  • Data retention — automatic and manual deletion of stale conversations, media, and logs.
  • Self-contained — no build step, no external libraries; a single installable plugin.

Installation

  1. Upload cxmedia-helpdesk.zip via Plugins → Add New → Upload Plugin, or extract the cxmedia-helpdesk folder into wp-content/plugins/.
  2. Activate the plugin. On activation it creates its database tables and the two custom roles.
  3. Open CXMedia Helpdesk → Settings and complete the WhatsApp configuration.

WhatsApp setup

The Settings page links the exact Meta destinations you need. In short:

  1. In the Meta App Dashboard, create a Business app and add the WhatsApp product.
  2. Under WhatsApp → API Setup, note your Phone Number ID and WhatsApp Business Account ID.
  3. In Business Settings → System Users, generate a permanent access token with the whatsapp_business_messaging and whatsapp_business_management permissions.
  4. Enter the Phone Number ID, WABA ID, access token, and your App Secret in CXMedia Helpdesk → Settings, then save (this generates a webhook verify token).
  5. Under WhatsApp → Configuration in your Meta app, set the Callback URL and Verify token shown on the Settings page, and subscribe to the messages field.

Verify the webhook by opening the callback URL with your real token in a browser:

https://YOURSITE/wp-json/cxmedia-helpdesk/v1/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123

A correct setup echoes back test123. Forbidden means the token doesn’t match (often the placeholder was left in, or Settings wasn’t saved yet).

Roles & permissions

Capability Administrator Manager Agent
See all conversations ✓
See own team’s conversations ✓ ✓
Operate only assigned conversations ✓
Reassign conversations ✓ ✓ (team) ✓ (to teammates)
Add / edit / delete team users ✓ ✓ (own team)
Delete conversations ✓ ✓ (scope)
Plugin settings ✓

A team is a manager plus the agents assigned to them. Managers manage their own team only; they are not granted WordPress’s site-wide user-management capabilities. Manage members on the Team page.

AI assistant (optional)

When enabled, new conversations are answered automatically by an AI bot that draws its knowledge from the CrossMediaBot plugin (its knowledge base, crawler index, Gemini model, and API key are reused). The bot answers only from that configured knowledge and hands off to a human agent when it cannot answer, when the customer asks for a person, or on any error.

  • Requires the CrossMediaBot plugin to be installed and configured; the Settings page shows whether it’s detected.
  • Bot replies are auto-sent and marked as Bot in the inbox for auditability.
  • Agents can Take over a bot conversation at any time (and hand it back).
  • If the assistant is disabled, the helpdesk runs as a pure human tool.

Data retention

Delete conversations that have had no message from the contact for a configurable number of months (default: 1).

  • Automatic deletion (opt-in) runs once a day.
  • Delete now (Settings, admins) purges everything past the window immediately.
  • Per-conversation delete (inbox, managers/admins) removes a single conversation.

Deletion removes the conversation, its messages, downloaded media files, the raw webhook payload log entries by age, and the contact record if it has no other conversations. Deletion is permanent.

Deployment notes

  • Public HTTPS is required for the webhook; Meta will not call localhost and expects a valid certificate.
  • WP-Cron must run for media downloads, notification emails, AI replies, and automatic retention. On low-traffic sites, configure a real system cron hitting wp-cron.php and set define('DISABLE_WP_CRON', true);.
  • Email: notifications use wp_mail(); most sites need an SMTP plugin for reliable delivery.
  • Nginx: the protected media directory ships with an Apache .htaccess deny rule. On Nginx add location ~ /wahd-media/ { deny all; } so media stays private.

Privacy

The plugin processes WhatsApp contact identifiers, profile names, message content, and media. Message content (and, if the AI assistant is enabled, the knowledge base) is transmitted to Meta and — for AI replies — to Google. The plugin sends no telemetry to its author. A ready-to-adapt privacy policy template is provided separately; publish and adapt it for your deployment.

For developers

  • REST namespace: cxmedia-helpdesk/v1 (inbox, conversations, agents, users, media, webhook).
  • Custom tables: wahd_contacts, wahd_conversations, wahd_messages, wahd_webhook_log.
  • Action hooks include wahd_message_stored, wahd_payload_received, wahd_media_fetched, wahd_conversation_deleted.
  • Filters include wahd_notification_recipients and wahd_notify_throttle.

Changelog

1.0

  • Initial release: WhatsApp Cloud API webhook, inbound processing, media fetch, and outbound sending with 24-hour window enforcement.
  • Agent inbox with conversation list, thread view, templates, and status control.
  • Role-based access: Administrator / Manager / Agent, team-scoped user management.
  • Email and in-dashboard notifications with unread badge.
  • Optional AI assistant with CrossMediaBot knowledge base and human escalation; bot-sent messages marked in the inbox.
  • Configurable automatic and manual data retention.

Credits

Developed by Gino Croes — Crossmedia297. For support or enquiries: admin@crossmedia297.com · https://crossmedia297.com