#2516: [Feature/Guide] Seamless Integration and Sidebar Visualization for Custom Messaging Channels (WeChat / Feishu)

Rationale & First Principles

By design, hermes-webui provides an elegant and clean web interface that aggregates webui sessions and canonical cli logs. However, when developers extend the hermes-agent underlying core by connecting external messaging gateways—such as WeChat (weixin) or Feishu (feishu)—their historical conversation records in state.db are silently swallowed or filtered out by the frontend presentation layer.

This issue happens due to two deeply-entrenched structural barriers in api/routes.py:

1. Closed Namespace Whitelist: The route gatekeeper blocks external channels via a strict checking rule in _is_known_messaging_source.
2. Aggressive Stale Sessions Eviction: The _should_hide_stale_messaging_session pipeline automatically flags background messaging sessions as "stale" and hides them if no active gateway live heartbeat/connection token is detected, effectively rendering offline chat history invisible.
3. Implicit Profile Isolation: Messaging sessions generated from external webhooks usually lack a dedicated profile tag, causing them to be wiped during active profile scoping filters.

This guide provides a clean, surgical patch to unleash full data sovereignty over your external channels while seamlessly supressing noises from developer tools (e.g., short-lived CLAUDE_CODE automation CLI logs).

---

Implementation Details

1. Backend Namespace Patching (api/routes.py)

Locate the following key interceptors in your backend route handler and align them to grant amnesty to your custom channels:

• Breakpoint A: Elevate Custom Source Authority Extend the messaging domain mapping to recognize weixin and feishu as verified citizens:

  def _is_known_messaging_source(raw_source) -> bool:
      return _normalize_messaging_source(raw_source) in _MESSAGING_RAW_SOURCES or _normalize_messaging_source(raw_source) in {'weixin', 'feishu'}
  

• Breakpoint B: Halt Stale Message Eviction for Specific Gateways Short-circuit the offline hiding logic at the top of the coordinator to keep your conversation assets permanently pinned:

def _should_hide_stale_messaging_session(session: dict, active_gateway_session_ids: set[str], active_gateway_sources: set[str]) -> bool:
    if str(session.get("source") or session.get("source_tag") or "").strip().lower() in {"weixin", "feishu"}: return False
    # ... original gateway checking

• Breakpoint C: Strict Channel Filtering Force the sidebar aggregation pipelines to render webui, weixin, and feishu explicitly, avoiding flooding the layout with micro-logs from other terminal executors:

# Apply strict channel filtering on webui native rows
webui_sessions = [s for s in webui_sessions if str(s.get("source") or s.get("source_tag") or "").strip().lower() in {"webui", "weixin", "feishu"}]

# Apply the same logic constraint on external deduped_cli rows
deduped_cli = [s for s in cli if s["session_id"] not in webui_ids and str(s.get("source") or s.get("source_tag") or "").strip().lower() in {"webui", "weixin", "feishu"}]

• Breakpoint D: Profile Matching Bypass Allow profile-agnostic external sessions to safely hydrate within the current viewport scope:

else:
    scoped = [s for s in merged
              if _profiles_match(s.get("profile"), active_profile) or str(s.get("source") or s.get("source_tag") or "").strip().lower() in {"weixin", "feishu"}]

2. Frontend Visual Resonance Styling (static/style.css)

To provide distinct sensory feedback for incoming threads, append the following styling block to map the iconic WeChat Green and Feishu Blue onto the session panel:

/* Custom Channel Badges: Visual Border Indicator for External Channels */
.session-item.cli-session[data-source-key="weixin"] { 
    border-left-color: #07C160 !important; 
}
.session-item.cli-session[data-source-key="weixin"]::after { 
    color: #07C160 !important; 
}
.session-item.cli-session[data-source-key="feishu"] { 
    border-left-color: #3370FF !important; 
}
.session-item.cli-session[data-source-key="feishu"]::after { 
    color: #3370FF !important; 
}

---

Expected Outcome

After restarting your control daemon (./ctl.sh restart), your hermes-webui console will elegantly preserve your standard workspace chats while placing the persistent messaging records at your fingertips, elegantly colored and filtered from systemic noise.