AI Ticketing — documentation

AI Ticketing · Joomla & WordPress · Documentation

AI Ticketing — documentation

AI Ticketing (pkg_aiticketing) is a native helpdesk for Joomla 5/6 with a lighter twin for WordPress. It works with no AI configured; add an NVIDIA NIM provider and it will classify a ticket, retrieve your knowledge base, and either auto-answer or escalate to a human — never auto-replying unless confident and KB-grounded.

What it is

On Joomla, AI Ticketing installs as a package bundling four extensions. The classic helpdesk only needs the first:

The WordPress twin (wp-aiticketing) is a lighter starter — ticket intake, a customer list, KB posts and admin triage via shortcodes; a separate build, so do not mix the ZIPs.

Requirements

• Joomla 5.4 or 6.1; the installer requires Joomla ≥ 5.0.0 and PHP ≥ 8.1.0 (8.3+ on Joomla 6).
• Database: MySQL 8 / MariaDB 10.6+ (tested on MariaDB 10.4); PostgreSQL install SQL ships too, with optional pgvector.
• WordPress twin: WordPress 6.0+ and PHP 8.1+.
• Administrator access to install and update; AI features additionally need an NVIDIA NIM key.

Installing creates its #__aitickets_* tables plus seed data; uninstalling drops them all.

Install & licence

Joomla. In System → Install → Extensions, upload pkg_aiticketing.zip, then open Components → AI Ticketing — the classic flow is ready at once. For private updates set your Download Key in Options → download_key or in System → Update → Update Sites.

Never click Rebuild Update Sites — it wipes stored Download Keys and cuts you off from updates. Re-enter the key if that happens.

WordPress. Use Plugins → Add New → Upload Plugin, upload wp-aiticketing and activate. Enter your licence key under AI Ticketing → Settings; without a valid licence, AI features and updates are blocked.

Where it lives and how it is used

Agents (Joomla). Everything is under Components → AI Ticketing, whose submenu holds Dashboard, Tickets, KB Articles, Categories, Priorities, Statuses, Teams, Team Users, Workflow Transitions, SLA Policies and Privacy (DSR). The ticket workspace carries the conversation, quick status change, an AI panel, a similar-tickets panel and sentiment badges.

Customers (Joomla front end). Create menu items for the views submit, tickets (my tickets) and ticket (detail + reply). Each ticket gets a public id like TKT-XXXXXXXX; guests return via a tokenised link (guest_token).

WordPress. Agents triage under the AI Ticketing menu and set status from the ticket's Ticket status metabox; publish the customer side with [aiticketing_submit], [aiticketing_my_tickets], [aiticketing_ticket] and [aiticketing_kb].

Configuration

Options live under Components → AI Ticketing → Options, in fieldsets. The AI fieldset holds the master switch ai_enabled (off → the NullAiProvider, a classic helpdesk), ai_provider (nvidia / gateway / none), the masked nvidia_api_key (the NVIDIA_API_KEY env var takes precedence, never stored in the DB), the chat model nvidia_chat_model (default meta/llama-3.3-70b-instruct) and ai_confidence_threshold (0.75 — below it, auto-reply escalates). Base URL defaults to integrate.api.nvidia.com/v1.

Further fieldsets cover Auto-reply, CSAT, Privacy, Front end (guest tickets, CAPTCHA, uploads, IP rate limit), Email, Channels and Tenant (multi-tenant + Stripe billing, off by default). The KB vector store kb_vector_backend is sql, pgvector or gateway; embedding/rerank models default to nvidia/nv-embedqa-e5-v5 and nvidia/llama-nemotron-rerank-1b-v2.

Ticket lifecycle and the AI assistant

Seeded statuses are new, open, pending_customer, pending_third_party, escalated, resolved, closed and reopened; priorities low…critical; channels web, backend, api, email, whatsapp, telegram, voice. SLA state is ok, near_breach (final 25% of the resolution window) or breached.

With AI on, a new ticket or customer reply queues an async autoreply job. When the scheduler runs it:

1. Classify the ticket (language, category, priority, sentiment, a wants_human signal).
2. RAG-retrieve the knowledge base via embeddings + cosine, optionally reranked.
3. If confident and grounded, post a public reply as ai_author_name (default "AI Assistant"), email the customer, and move to autoreply_status (default pending_customer).
4. Otherwise escalate to a human: set escalation_status, assign escalation_user_id, post an internal note and notify staff.

Escalation triggers: wants-a-human, sentiment at or below escalate_sentiment_below (−0.4), low confidence, or no KB match above kb_match_threshold (0.45); with require_ai_consent on and consent missing the job skips (no_ai_consent). Jobs are claimed atomically, so overlapping cron runs cannot double-send.

Agents also get a manual AI tool — classify or draft writes a suggestion they approve, reject, or apply; the AI never touches a ticket a human owns.

Under the Task – AI Ticketing plugin (created in System → Scheduled Tasks), four routines are available: aiticketing.process_ai_queue (~5 min), aiticketing.sla_monitor (~15 min), aiticketing.cleanup_retention (daily) and aiticketing.email_fetch — add the last one to turn on email-to-ticket.

Notifications and email-to-ticket

Notifications. Toggle staff alerts (notify_new_ticket, notify_escalation), the customer auto-reply email (autoreply_email_customer, on), the CSAT invite (csat_email) and an optional public escalation_holding_message.

Email-to-ticket. With email_fetch_enabled on, the task plugin imports RFC822 .eml files from email_spool_path (optionally fetching unread IMAP mail first via email_imap_host, port 993); a protected webhook.email task accepts RFC822 or JSON via email_webhook_token. Inbound webhook.whatsapp, webhook.telegram and webhook.voice append to the newest open ticket; chat channels need external Meta/Telegram setup.

Web services (REST API)

Enable plg_webservices_aiticketing plus a Joomla API authentication plugin, and send Authorization: Bearer <token>. Routes live under /api/index.php:

The list honours whitelisted filter[...] params: status_id, priority_id, category_id, assigned_user_id, sla_state and search.

The API reuses the UI's models and ACL and excludes ai_consent and guest_token. Expected: 401 unauthenticated, 403 low-privilege, 409 on AI routes when AI is off.

Privacy and data-subject requests

The Privacy (DSR) admin page runs a subject-access export (JSON) and an anonymize by email. The bundled plg_privacy_aiticketing also handles native Users → Privacy requests (onPrivacyExportRequest, onPrivacyCanRemoveData), calling the same export/anonymize.

Data controls sit in the Privacy fieldset: redact_pii_in_logs (on — masks emails, IBANs, phones and coarsens the audit-log IP), retention_days (default 730; 0 disables the purge), and the AI-consent gate require_ai_consent + ai_consent_text. Every state change is CSRF-checked and ACL-guarded, and an append-only audit log records who did what.

By design, any agent with reply/manage permission sees every ticket in their tenant — full-queue visibility, the intended small-team workflow; cross-tenant isolation is always enforced.

Updates & licence

• Check the installed version under System → Manage → Extensions first.
• Joomla: System → Update → Extensions, Check for Updates, then update the package (private updates require the active Download Key). Schema migrations apply once each via #__schemas.
• WordPress: the twin self-updates through its own updater once a valid licence key is saved.

Troubleshooting

• AI does nothing. Confirm ai_enabled=1, a key is set (or NVIDIA_API_KEY exported), and the Task – AI Ticketing plugin is enabled with process_ai_queue scheduled — auto-reply is asynchronous.
• Everything escalates. The KB is probably empty or unindexed: add KB articles and reindex, or lower kb_match_threshold / ai_confidence_threshold. No grounded KB hit always escalates by design.
• Update not offered. Re-enter the Download Key and clear the update cache; if you clicked Rebuild Update Sites, the key was wiped.

FAQ

• Do I need an AI key?

  No. With ai_enabled off it is a full classic helpdesk on the NullAiProvider; add an NVIDIA NIM key only for classification, auto-reply and RAG.

• Which provider, and where does the key go?

  NVIDIA NIM or a self-hosted AI Gateway. Prefer the NVIDIA_API_KEY environment variable over the nvidia_api_key field — it takes precedence and is never written to the database or logs.

• Will the AI answer a customer on its own?

  Only when confident and KB-grounded, on a ticket no human owns; otherwise it escalates, and manual drafts always await agent review.

• Can customers submit by email or WhatsApp?

  Yes — .eml import (optionally over IMAP) plus WhatsApp, Telegram and voice webhooks feed tickets. Each channel needs its own token.

• Can I run the Joomla ZIP on WordPress?

  No — install pkg_aiticketing on Joomla and the separate wp-aiticketing build on WordPress.