Platform announcements¶
These user-environment announcement reads require qot:read, extension_version: 1, and --enable-desktop-phase2-reads (default OFF). Live backend availability remains UNVERIFIED.
| API / CLI | REST POST | Additional request fields |
|---|---|---|
GetPlatformAnnouncements / platform-announcements |
/api/platform-announcements |
page_params optional array; absent/empty requests full list |
GetPlatformAnnouncementsByIds / platform-announcements-by-ids |
/api/platform-announcements-by-ids |
nonempty notice_ids array of signed integers |
MCP tools are futu_get_platform_announcements and futu_get_platform_announcements_by_ids; supply the request as c2s_json, with optional api_key. The same typed requests are available through Gateway and gRPC.
futucli platform-announcements --c2s-json '{"extension_version":1}'
futucli platform-announcements-by-ids --c2s-json '{"extension_version":1,"notice_ids":[7]}'
Request and response¶
Each page filter preserves optional page_id, params_type and params bytes (JSON byte array). Type 0 encodes StockDetailPageParams (stock_id, market_id, market_type); type 1 encodes PageParamList (stock_id_list, market_id_list, market_type_list). These are bound protocol extensions; the normal full-list request omits page filters. Do not substitute internal command IDs or unrelated messages for these bytes. Language and client identity come from the current connection; callers cannot override user or broker identity.
Responses contain optional backend_code, backend_message, raw notices, and local owner_epoch/revision. Each Notice preserves all optional fields: notice_id, start_time, end_time, pages, title, details, link, style, details_link_keyword, details_link, update_time, sort, details_html, popup_type, popup_auto, start_time_int64, end_time_int64, update_time_int64. Times are Unix seconds; legacy 32-bit and newer 64-bit values remain separate. Related pages retain optional page ID and filter type/content bytes. Unknown filter types remain unknown, never global eligibility.
Text, HTML and links are data. The gateway never executes HTML, opens URLs, or substitutes missing content. Render them as safe text or use a controlled rich-text renderer; never assign returned HTML directly to an untrusted page. CLI JSON output escapes control characters. The API exposes raw time windows and does not simulate popup, close or display-throttling state.
Snapshot notifications¶
UpdatePlatformAnnouncement carries a complete current cache snapshot: notices, local owner_epoch, and revision. Replace the prior snapshot for that owner; do not append it as a delta. These counters are local lifecycle/order markers, not backend message IDs or globally comparable sequence numbers. Gateway uses its normal notification opt-in; REST WebSocket clients use subscribe-notify and require qot:read; gRPC uses the existing notification stream.
The cache contains observed announcements and does not claim every backend record is present after an incremental query. A nonempty full response retires missing IDs, but a successful empty full response preserves the cache. Raw read results still reflect that empty response. Specified pages and IDs never retire unrelated records. Higher sort replaces a record; equal sort updates text/link fields only when HTML changes. An offline event removes the record immediately. Late responses and queued snapshots from obsolete owners or revisions cannot restore it.
An online event marks IDs for refresh. Refresh failure preserves pending IDs and stops automatic attempts; the next online event or explicit read can retry. No timer-based polling or infinite retry loop is started. Notifications may coalesce intermediate states. After disconnect or stream loss, explicitly read the full list to recover; raw query results and cached replacement notifications have distinct completeness semantics. User/session, connection, language or main-broker changes invalidate old ownership. Transport/status/decode or stale-owner failures return errors, not fabricated empty success.