Fluent support

Below is the full documentation / handover for the current plugin.

---

1. YDB FluentSupport Tools — Full Documentation

1. 1. Plugin name

```text
YDB FluentSupport Tools
```

Current checkpoint:

```text
v14 — Concurrency + Portal Layout + Agent-Created Ticket Signature
```

Current plugin version in header:

```text
0.1.14
```

Plugin folder:

```text
wp-content/plugins/ydb-fluentsupport-tools/
```

Main plugin file:

```text
wp-content/plugins/ydb-fluentsupport-tools/ydb-fluentsupport-tools.php
```

---

1. 2. Purpose

This plugin extends FluentSupport without modifying FluentSupport core/pro files.

It currently adds/customizes:

```text
1. Near real-time ticket concurrency badge
2. Native FluentSupport watcher badge suppression
3. Support agent portal compatibility fixes
4. Support portal/list width/layout control
5. Agent signature support for agent-created ticket emails
6. Admin diagnostic page
```

The plugin is intentionally built as a normal WordPress plugin, not currently as an MU plugin.

---

1. 3. Important rule

Do not modify FluentSupport core/pro plugin files.

All custom behavior should stay inside:

```text
wp-content/plugins/ydb-fluentsupport-tools/
```

---

1. 4. Current file structure

Expected structure:

```text
wp-content/plugins/
ydb-fluentsupport-tools/
ydb-fluentsupport-tools.php

includes/
            config.php
            helpers.php
            admin-page.php
            concurrency.php
            elementor-compat.php
            native-badge-compat.php
            ticket-list-layout.php
            portal-fullwidth.php
            agent-signature-smartcode.php

assets/
            js/
                concurrency.js
```

---

1. 5. Main plugin loader

Main file:

```text
ydb-fluentsupport-tools.php
```

It defines:

```text
YDB_FS_TOOLS_VERSION
YDB_FS_TOOLS_FILE
YDB_FS_TOOLS_DIR
YDB_FS_TOOLS_URL
```

It uses a safe include helper:

```php
ydb_fs_tools_safe_include('includes/file-name.php');
```

This allows the plugin to continue loading even if one include file is missing, and stores include errors in:

```php
$GLOBALS['ydb_fs_tools_include_errors']
```

The main loader currently includes these modules:

```php
ydb_fs_tools_safe_include('includes/config.php');
ydb_fs_tools_safe_include('includes/helpers.php');
ydb_fs_tools_safe_include('includes/agent-signature-smartcode.php');
ydb_fs_tools_safe_include('includes/elementor-compat.php');
ydb_fs_tools_safe_include('includes/native-badge-compat.php');
ydb_fs_tools_safe_include('includes/ticket-list-layout.php');
ydb_fs_tools_safe_include('includes/portal-fullwidth.php');

if (defined('YDB_FS_TOOLS_ENABLE_CONCURRENCY') && YDB_FS_TOOLS_ENABLE_CONCURRENCY) {
ydb_fs_tools_safe_include('includes/concurrency.php');
}

ydb_fs_tools_safe_include('includes/admin-page.php');
```

---

1. 6. Configuration

Configuration file:

```text
includes/config.php
```

This controls whether concurrency is active.

Expected constant:

```php
YDB_FS_TOOLS_ENABLE_CONCURRENCY
```

When enabled, the plugin loads:

```text
includes/concurrency.php
assets/js/concurrency.js
```

---

1. 7. Ticket concurrency feature

1. Purpose

The concurrency system warns an agent when another agent is already viewing the same ticket.

Example use case:

```text
Agent A opens ticket 17.
Agent B opens ticket 17.
Agent B immediately sees a red warning badge.
```

1. Current accepted behavior

The current accepted badge is:

```text
Red
Bottom-right
Wide enough to read clearly
Slow flashing
Text:
Ticket already open
by {agent name}
```

Example:

```text
Ticket already open
by Maurizio
```

1. Why custom badge was needed

FluentSupport has a native active-agents / people-watching feature, but the timing was too slow and not prominent enough.

The custom plugin improves this by using:

```text
Short heartbeat interval
Shorter fallback TTL
Immediate leave signal when changing ticket
Server-side cleanup when agent moves from one ticket to another
```

1. Timing baseline

Current logic uses approximately:

```text
Heartbeat interval: 5 seconds
Fallback TTL: around 25 seconds
```

This means stale presence disappears much faster than the original FluentSupport behavior.

1. Important improvement already added

The plugin prevents this stale case:

```text
Agent A opens ticket 17.
Agent B opens ticket 17.
Agent B changes to ticket 18.
Ticket 17 should quickly stop showing Agent B as present.
```

This is handled by server-side “single active ticket per user” cleanup.

---

1. 8. Concurrency files

1. PHP module

```text
includes/concurrency.php
```

Responsibilities:

```text
Registers REST endpoints
Stores active ticket viewers
Uses WordPress transients
Cleans stale user/ticket presence
Returns list of other users currently viewing the same ticket
```

1. JavaScript module

```text
assets/js/concurrency.js
```

Responsibilities:

```text
Detects FluentSupport ticket URL/hash changes
Extracts ticket ID from routes like #/tickets/{id}/view
Sends heartbeat to server
Sends leave signal when changing ticket or unloading page
Displays custom red badge
Hides/removes old debug display unless reactivated
```

1. Debug code

Debug info was previously useful and should remain commented, not deleted.

It can be reactivated later if needed.

---

1. 9. Native FluentSupport badge suppression

File:

```text
includes/native-badge-compat.php
```

Purpose:

```text
Hide FluentSupport's own native "People Watching" / active agents badge.
```

Reason:

```text
The native badge was slower and visually duplicated the custom YDB badge.
```

Current rule:

```text
Keep FluentSupport DOM safe.
Do not edit FluentSupport plugin files.
Hide the native visual badge only.
```

---

1. 10. Frontend agent portal compatibility

File:

```text
includes/elementor-compat.php
```

Purpose:

```text
Protect the frontend FluentSupport agent portal from frontend scripts that treat hash routes as CSS selectors.
```

Problem solved:

On the frontend support portal, URLs like:

```text
/support-agent-portal/#/tickets/18/view
```

could cause frontend/theme/Elementor scripts to misinterpret:

```text
#/tickets/18/view
```

as a CSS selector.

This caused JavaScript errors.

The compatibility module adds guards to prevent that problem.

---

1. 11. Support portal/list layout

Files:

```text
includes/ticket-list-layout.php
includes/portal-fullwidth.php
```

1. Purpose

Adjust the frontend support-agent portal layout without editing the theme or FluentSupport files.

Current accepted layout:

```text
Support portal/list content centered
Width around 80%
Not full browser width
Wide-screen-first layout
Mobile-specific version prepared but not enabled/finalized
```

1. Background

The ticket list was constrained by FluentSupport internal wrappers, especially around:

```text
.fs_box_wrapper
```

The plugin now targets the correct wrappers.

---

1. 12. Agent signature problem

1. Original problem

The agent successfully set a signature in FluentSupport.

Normal ticket replies could use FluentSupport’s built-in agent signature behavior.

But when an agent created a new ticket directly from FluentSupport, the outgoing customer email used this separate template:

```text
Ticket Created by Agent (To Customer)
```

The normal agent signature did not appear there.

---

1. 13. Wrong approach that did not work

We first tried adding this smartcode:

```text {{agent.signature}}
```

to the FluentSupport template.

This did not work on this installation.

Testing proved:

```text
The file loaded.
The email template was correct.
But FluentSupport did not pass this specific email through the expected smartcode parser.
```

So this should not be used for agent-created ticket emails:

```text {{agent.signature}}
```

---

1. 14. Working signature solution

File:

```text
includes/agent-signature-smartcode.php
```

Working marker:

```text
[[YDB_AGENT_SIGNATURE]]
```

This marker is inserted into the FluentSupport email template.

The plugin replaces it at the final WordPress email stage using:

```php
wp_mail
```

This worked successfully.

---

1. 15. Required FluentSupport email template

Go to:

```text
WordPress Admin
→ Fluent Support
→ Business Inboxes
→ your inbox
→ View Settings
→ Email Settings
→ Ticket Created by Agent (To Customer)
→ Edit
```

Template body should be:

```text {{response.full_content}}

[[YDB_AGENT_SIGNATURE]]
```

Remove all test lines, such as:

```text
YDB TEST LINE
YDB WP_MAIL TOKEN WORKS {{agent.signature}}
```

---

1. 16. Signature lookup behavior

The plugin replaces:

```text
[[YDB_AGENT_SIGNATURE]]
```

with the current logged-in agent’s signature.

It searches in this order:

```text
1. WordPress user meta
2. FluentSupport custom tables
```

Expected FluentSupport tables:

```text
wp_fs_persons
wp_fs_meta
```

The real prefix may differ if the WordPress database prefix is not `wp_`.

The plugin uses:

```php
$wpdb->prefix . 'fs_persons'
$wpdb->prefix . 'fs_meta'
```

So it automatically respects the WordPress table prefix.

---

1. 17. Signature behavior rules

1. Normal ticket replies

Use FluentSupport’s native agent signature behavior.

Do not use the custom marker unless needed.

1. Agent-created tickets

Use this marker in the template:

```text
[[YDB_AGENT_SIGNATURE]]
```

1. Do not use this for agent-created tickets

```text {{agent.signature}}
```

Because it did not work in this installation.

---

1. 18. Current safe email template rules

1. For normal reply email

Template:

```text
Replied by Agent (To Customer)
```

Use FluentSupport normal body/signature behavior.

1. For agent-started email

Template:

```text
Ticket Created by Agent (To Customer)
```

Use:

```text {{response.full_content}}

[[YDB_AGENT_SIGNATURE]]
```

---

1. 19. Testing history

1. Test 1 — Business Inbox template problem

Old signature was found in the Business Inbox email template, not in the agent profile.

Result:

```text
Old signature removed from inbox template.
```

1. Test 2 — Smartcode test

Tried:

```text {{agent.signature}}
```

Result:

```text
Did not appear.
```

1. Test 3 — Plugin load test

Added admin notice.

Result:

```text
agent-signature-smartcode.php loaded successfully.
```

1. Test 4 — Smartcode parser test

Tried to replace:

```text {{agent.signature}}
```

using FluentSupport smartcode filter.

Result:

```text
Did not run for this email flow.
```

1. Test 5 — wp_mail marker test

Added:

```text
[[YDB_AGENT_SIGNATURE]]
```

and temporarily replaced it with:

```text
YDB WP_MAIL TOKEN WORKS
```

Result:

```text
Worked.
```

1. Test 6 — Real signature replacement

Replaced marker with real current agent signature.

Result:

```text
Perfect / confirmed working.
```

---

1. 20. Temporary test code status

All temporary test strings should be removed from live templates:

```text
YDB TEST LINE
YDB WP_MAIL TOKEN WORKS
```

All temporary admin notices should also be removed from production code unless intentionally kept for diagnostics.

The final production file should not show green admin notices every time.

---

1. 21. Current production behavior

The plugin now supports:

```text
Agent creates ticket manually in FluentSupport
Customer receives "Ticket Created by Agent" email
Email body includes response content
Email body includes the current agent's configured signature
```

Template:

```text {{response.full_content}}

[[YDB_AGENT_SIGNATURE]]
```

---

1. 22. Admin diagnostic page

File:

```text
includes/admin-page.php
```

Purpose:

```text
Show plugin status
Show whether modules loaded
Show include errors
Help diagnose missing files
```

This is useful because the plugin uses safe includes.

If a file is missing, it should be reported instead of causing a fatal crash.

---

1. 23. Known good checkpoint

Current known good checkpoint:

```text
YDB FluentSupport Tools v14
```

Includes:

```text
v13 portal/concurrency baseline
+
v14 agent-created ticket signature marker
```

Known-good plugin folder:

```text
wp-content/plugins/ydb-fluentsupport-tools/
```

Known-good signature file:

```text
wp-content/plugins/ydb-fluentsupport-tools/includes/agent-signature-smartcode.php
```

Known-good FluentSupport template marker:

```text
[[YDB_AGENT_SIGNATURE]]
```

---

1. 24. Upgrade / backup recommendation

Before further changes, create a zip backup of:

```text
wp-content/plugins/ydb-fluentsupport-tools/
```

Suggested filename:

```text
ydb-fluentsupport-tools-v14-agent-signature-working.zip
```

This should be the new safe baseline.

---

1. 25. Future improvements

Possible next improvements:

```text
1. Add plugin settings page to enable/disable each module.
2. Add configurable heartbeat interval and TTL.
3. Add mobile-specific support portal layout.
4. Add admin toggle for badge position: bottom-right / top-right.
5. Add admin toggle for badge text.
6. Add support for showing multiple agents in the badge.
7. Add log/debug mode for concurrency events.
8. Add diagnostic button to test agent signature detection.
9. Add fallback if no agent signature exists.
10. Add per-inbox signature behavior if needed.
```

---

1. 26. Important future warning

The signature feature depends on the current logged-in agent at the moment the email is sent.

This is correct for:

```text
Agent manually creates a ticket while logged in
```

But if FluentSupport later sends background/cron emails without a logged-in user, the plugin may not know which agent signature to use.

For the current tested flow, it works.

---

1. 27. Short handover for next session

```text
We have a WordPress plugin named YDB FluentSupport Tools under wp-content/plugins/ydb-fluentsupport-tools/. It extends FluentSupport without modifying core/pro files.

Current checkpoint is v14. v13 handled ticket concurrency, native watcher badge suppression, frontend support-agent portal hash compatibility, and 80% centered portal/list layout. v14 adds working agent signature support for agent-created ticket emails.

For normal FluentSupport replies, use FluentSupport’s built-in agent signature.

For agent-created tickets, FluentSupport’s {{agent.signature}} did not work in this installation. The working solution is a custom marker handled through wp_mail.

Template:
Fluent Support → Business Inboxes → selected inbox → View Settings → Email Settings → Ticket Created by Agent (To Customer)

Body: {{response.full_content}}

[[YDB_AGENT_SIGNATURE]]

File:
wp-content/plugins/ydb-fluentsupport-tools/includes/agent-signature-smartcode.php

The marker is replaced with the current logged-in agent’s FluentSupport signature. The code searches WordPress user meta first, then FluentSupport tables such as fs_persons and fs_meta.

Do not use {{agent.signature}} for this specific agent-created ticket flow.
```