# Videochat host extension API v1 This additive PHP contract is shared by Paid Videochat, 2Way VideoCalls and Broadcast Live Video. It prepares separate app companions; it does not install Pro, change current licenses/quality limits, grant streaming access, or add a managed payment engine. With no extension registered, built-in apps are used. Register filters from a local plugin before they are used. Every callback must check `host_slug` and, for runtime assets/config, `app_family`. Context contains `schema=videowhisper.videochat-host/1`, `contract=1`, `host_slug`, `host_version`, `app_family` (`host`, `legacy`, `webrtc`), `instance`, `root_id`, `settings_page` and known settings tabs. It contains no account secrets or wallet authority. Labels are supplied lazily through a host callback, outside option defaults. ## Settings and defaults | Hook | Arguments / result | | --- | --- | | `videowhisper_videochat_defaults_v1` | Filter `(defaults, context)`; change existing keys with the same PHP type. Saved values, including zero/false/empty strings, overlay defaults. Unknown keys are discarded; add new settings through schema instead. No automatic reset of saved choices. | | `videowhisper_videochat_settings_tabs_v1` | Filter `(tabs, context)`; map `vendor.tab` to `label` and optional `capability`. Labels must be localized by their owner. Built-in tabs cannot be replaced. | | `videowhisper_videochat_settings_schema_v1` | Filter `(fields, context)`; map `vendor.field` to `tab`, `label`, `type`, optional `default`, `capability`, `min`, `max`, `max_length`, `choices`, `sanitize_callback`, `validate_callback`. | | `videowhisper_videochat_settings_section_v1` | Action `(context, tab, values)` after the separate extension form, including existing tabs. Output must be escaped by its owner. | Types: `string`, `integer`, `number`, `boolean`, `select`. Select choices are a value/label map. Callbacks receive `(typed_value, context)`; a validator must return exactly `true`. All fields require `manage_options` plus any extra registered capability. The host validates nonce, tab, registered field IDs, scalar shape, type and bounds before writing any value. Unknown fields, another tab's fields and unauthorized fields reject the whole submission. String fields are single-line plain text. These fields are not a credential store. Extension values live separately in `vw_videochat_extensions_`. The form posts to `admin-post.php?action=vw_videochat_settings_v1`, with a host/tab-specific nonce. It never enters the older general option-saving loop. Only submitted allowed keys change; other tabs/providers are retained. Removing an add-on hides its controls and retains its saved values. This version adds controls at the end of existing tabs; it does not reorder native fields or change how their existing forms save. Example (a plugin owns/localizes its labels): ```php add_filter( 'videowhisper_videochat_settings_tabs_v1', function ( $tabs, $ctx ) { if ( 'ppv-live-webcams' === $ctx['host_slug'] ) { $tabs['example.quality'] = array( 'label' => __( 'Quality profiles', 'example-addon' ) ); } return $tabs; }, 10, 2 ); add_filter( 'videowhisper_videochat_settings_schema_v1', function ( $fields, $ctx ) { if ( 'ppv-live-webcams' === $ctx['host_slug'] ) { $fields['example.profile'] = array( 'tab' => 'example.quality', 'type' => 'select', 'label' => __( 'Default profile', 'example-addon' ), 'default' => 'conservative', 'choices' => array( 'conservative' => __( 'Conservative', 'example-addon' ) ), ); } return $fields; }, 10, 2 ); ``` Changing defaults for native streaming keys is a separate filter operation. A future Pro “Apply profile” action must explicitly show old/new saved values, verify capability/nonce and clamp them to the verified service/browser limits. The schema form intentionally cannot write arbitrary existing host options. ## Local app providers `videowhisper_videochat_app_providers_v1` filters `(providers, context)`. Use a namespaced provider ID, e.g. `example.videochat`. Each descriptor declares: ```php array( 'contract' => 1, 'family' => 'webrtc', // or legacy 'format' => 'module', // classic for legacy 'priority' => 10, // higher wins; registration order breaks ties 'plugin_file' => __FILE__, // actual local plugin bootstrap in WP_PLUGIN_DIR 'hosts' => array( 'ppv-live-webcams' => array( 'min' => '7.6.0', 'max' => '7.6.99' ), ), 'scripts' => array( 'apps/app.js' => '...64 lowercase SHA-256 hex characters...' ), 'styles' => array( 'apps/app.css' => '...64 lowercase SHA-256 hex characters...' ), ); ``` Check `method_exists( $host_class, 'videochatContext' )` and contract version 1 when integrating older hosts. Use the version that first ships this API as the compatibility floor; the example is not a claim that a particular version has been publicly released. The provider owns its dependency notices, reproducible build and any source distribution obligations. Private app code is never placed in Free packages. `videowhisper_videochat_app_assets_v1` filters `(descriptor, context, provider_id)` before validation. Scripts/styles are ordered relative path/hash maps. All declared files must exist, remain inside the provider root after symlink resolution and match their digest. URLs are derived locally with `plugins_url`; remote runtime URLs and traversal are rejected. A WebRTC module has exactly one entry script; imported build chunks live beside it. Legacy scripts enqueue in manifest order with dependencies; list runtime/vendor before main. A broken manifest never mixes some Pro files with built-in files: the next compatible provider is tried, then the built-in app. Selection is pinned per host/family for that page request. No live call is hot-swapped or remotely unlocked. The provider must implement the existing bootstrap/mount contract: - Legacy: `window.VideoWhisper`, root `videowhisperVideochat`, classic scripts. - WebRTC: `window.videowhisperConfig.configUrl`, root `root`, module entry. Host-created authentication/config URLs, access checks, paid-engine selection, room identity, media policy and billing remain in the host. The observer action `videowhisper_videochat_app_enqueued_v1(context, provider_id, handle)` runs when the shared loader enqueues a provider or the WebRTC built-in entry. Legacy fallback still uses its existing loader/diagnostics. The current apps use global bootstrap objects and one app mount per page; this stage does not introduce multiple isolated React apps on one page. ## Extension runtime configuration `videowhisper_videochat_app_config_v1(extensions, context)` returns a map of namespaced JSON values, e.g. `example.ui`. The bounded result (16 KiB) becomes `window.VideoWhisper.extensions` or `window.videowhisperConfig.extensions`. Unknown non-namespaced top-level keys are removed. The filter cannot replace host authentication, config URL, payer/rates, room, media or permission fields. Do not put credentials, personal records, wallet authority or executable code in these public UI values. Inline JSON is encoded against script-tag injection. CRM/Updater downloads and entitlement checks are a later companion stage. Do not make license/CRM requests from billing status ticks. Managed payments require a separately qualified server/wallet protocol and media enforcement.