Build Zoom Virtual Agent

Zoom Virtual Agent - Android

Official docs:

• https://developers.zoom.us/docs/virtual-agent/android/

Quick Links

1. concepts/webview-lifecycle.md 2. examples/js-bridge-patterns.md 3. references/android-reference-map.md 4. troubleshooting/common-issues.md

Integration Model

• Host campaign URL in Android WebView.
• Inject runtime context (window.zoomCampaignSdkConfig).
• Register JavaScript bridge for exitHandler, commonHandler, support_handoff.
• Apply URL policy via shouldOverrideUrlLoading and optional multi-window callbacks.

Hard Guardrails

• Initialize handlers before expecting JS callbacks.
• Treat legacy openURL command handling as compatibility path only.
• Prefer DOM links or window.open handling plus explicit native routing.

Chaining

• Product-level patterns: ../SKILL.md
• Contact Center mobile scope: ../../contact-center/android/SKILL.md

Android WebView Lifecycle

1. Build intent with URL and policy flags. 2. Configure WebView (JavaScriptEnabled, optional multi-window support). 3. Inject user context config before page interaction. 4. Inject bridge script on zoomCampaignSdk:ready. 5. Handle callbacks via @JavascriptInterface. 6. Route URL actions and handoff payloads. 7. Close view and clean references on exit.

Android JS Bridge Patterns

Inject Native Bridge

private fun injectJavaScriptFunction() {
    val js = """
        javascript: window.addEventListener('zoomCampaignSdk:ready', () => {
            if (window.zoomCampaignSdk) {
                window.zoomCampaignSdk.native = {
                    exitHandler: { handle: function() { AndroidExit.handleExit(); } },
                    commonHandler: { handle: function(e) { AndroidCommon.handleCommon(JSON.stringify(e)); } }
                };
            }
        });
    """.trimIndent()
    webView.loadUrl(js)
}

Handoff Relay

private fun injectHandoffFunction() {
    val js = """
        javascript: window.addEventListener('support_handoff', (e) => {
            AndroidHandoff.handleHandoff(JSON.stringify(e.detail));
        });
    """.trimIndent()
    webView.loadUrl(js)
}

URL Governance

• Use shouldOverrideUrlLoading for in-app vs system-browser policy.
• Use multi-window callbacks for target="_blank" handling.

Android Reference Map

Core Docs

• Get started: https://developers.zoom.us/docs/virtual-agent/android/get-started/
• Integration scenarios: https://developers.zoom.us/docs/virtual-agent/android/integration-scenarios/
• JavaScript events: https://developers.zoom.us/docs/virtual-agent/android/javascript-events/
• Resources: https://developers.zoom.us/docs/virtual-agent/android/resources/

Observed Sample Patterns

• Java and Kotlin implementations follow the same bridge contract.
• Bridge command routing centers around commonHandler JSON payloads.
• support_handoff events are emitted from JS and consumed in native layer.

Android Common Issues

Bridge Callback Never Fires

• Ensure JS bridge injection runs after page load and SDK readiness.
• Ensure addJavascriptInterface names match injected handler names.

Link Opens in Wrong Context

• Implement both shouldOverrideUrlLoading and multi-window behavior.
• Distinguish _self and _blank paths explicitly.

Deprecated openURL Path

• Avoid relying on {"cmd":"openURL"...} as primary flow.
• Prefer anchor or window.open plus native interception policy.

Campaign Works on Web but Not Mobile

• Verify campaign targeting includes mobile.
• Verify same API key/env pair used in WebView build.

Architecture and Lifecycle

Architecture

Web or Mobile Host App
  -> Zoom Campaign SDK (zcc-sdk.js)
  -> Campaign or Entry routing
  -> Bot conversation state
  -> Optional native bridge (Android/iOS)
  -> Optional backend automation (OAuth + REST KB APIs)

Lifecycle

1. Provision bot flow and campaign/entry configuration. 2. Embed SDK snippet and provide runtime config (apikey, env, user context). 3. Wait for readiness, then register event callbacks. 4. Start or show engagement (open, show). 5. React to events (open, close, engagement_started, engagement_ended). 6. For mobile wrappers, forward bridge events (support_handoff, exit, URL commands). 7. End session (endChat) and detach handlers.

Version Drift Notes

• Documentation now uses "Virtual Agent" naming.
• Official sample repositories still contain older naming (virtual-assistant, liveSDK) that can mislead search and code mapping.

iOS WKWebView Lifecycle

1. Create WKWebViewConfiguration and WKUserContentController. 2. Add user scripts for context injection and bridge handlers. 3. Register message handlers before navigation. 4. Push/present webview controller with campaign URL. 5. Process callbacks in userContentController:didReceiveScriptMessage:. 6. Route navigation and external links in WKNavigation delegate callbacks. 7. Remove message handlers during teardown.

iOS JS Bridge Patterns

Inject Exit and Common Handlers

let exitHandlerScript = """
window.addEventListener('zoomCampaignSdk:ready', () => {
  if (window.zoomCampaignSdk) {
    window.zoomCampaignSdk.native = {
      exitHandler: { handle: function() { window.webkit.messageHandlers.zoomLiveSDKMessageHandler.postMessage('close_web_vc'); } },
      commonHandler: { handle: function(e) { window.webkit.messageHandlers.commonMessageHandler.postMessage(JSON.stringify(e)); } }
    };
  }
});
"""

Inject Support Handoff

let handoffScript = """
window.addEventListener('support_handoff', (e) => {
  window.webkit.messageHandlers.support_handoff.postMessage(JSON.stringify(e.detail));
});
"""

URL Handling Policy

• WKNavigationActionPolicyAllow for trusted in-app routes.
• UIApplication.openURL for system-browser policy.
• Optional in-app browser route (for example SFSafariViewController).

iOS Reference Map

Core Docs

• Get started: https://developers.zoom.us/docs/virtual-agent/ios/get-started/
• Integration scenarios: https://developers.zoom.us/docs/virtual-agent/ios/integration-scenarios/
• JavaScript events: https://developers.zoom.us/docs/virtual-agent/ios/javascript-events/
• Resources: https://developers.zoom.us/docs/virtual-agent/ios/resources/

Observed Sample Patterns

• Objective-C and Swift variants expose equivalent bridge behavior.
• Message handler constants in sample code still use legacy naming.
• URL routing policy is split between delegate interception and message-handler command processing.

iOS Common Issues

Message Handlers Not Triggering

• Ensure WKUserScript and handlers are registered before page load.
• Verify handler names exactly match injected JS references.

URL Opens Unexpectedly

• Explicitly branch in decidePolicyForNavigationAction.
• Handle _blank/window.open paths as separate cases.

Deprecated openURL Command Drift

• Treat command-based open URL as fallback.
• Prefer DOM links and window.open with delegate-driven routing.

File Download Inconsistency

• Download behavior via WKWebView requires iOS 14.5+ support paths.

Environment Variables

Web Embed Runtime

• ZVA_API_KEY: Virtual Agent API key for campaign SDK script.
• ZVA_ENV: Deployment region (us01 or eu01).
• ZVA_CAMPAIGN_ID: Optional campaign identifier when switching campaigns programmatically.
• ZVA_ENTRY_ID: Optional entry ID path when campaign mode is not used.

Knowledge Base API Automation

• ZOOM_ACCOUNT_ID: Account ID for Server-to-Server OAuth app.
• ZOOM_CLIENT_ID: S2S OAuth client ID.
• ZOOM_CLIENT_SECRET: S2S OAuth client secret.
• ZOOM_ACCESS_TOKEN: Runtime bearer token (short-lived).
• ZVA_KB_ID: Knowledge base ID for custom API sync.

Where to Find Keys

1. Zoom Marketplace app credentials: OAuth app in Marketplace. 2. Virtual Agent campaign/entry settings: Zoom admin portal AI Management. 3. KB ID: Knowledge Base settings in AI Management.

Samples Validation

Validated repositories:

• https://github.com/zoom/virtual-assistant-android-sample
• https://github.com/zoom/virtual-assistant-iOS-sample

Latest commit observed during validation:

• Android sample: faab2b6 (2024-10-16), commit message references OpenUrl deprecation.
• iOS sample: dd31e95 (2024-10-16), commit message references URL opening method update.

Confirmed Relevant Patterns

• zoomCampaignSdk:ready event gating before native bridge registration.
• window.zoomCampaignSdk.native.exitHandler/commonHandler bridge contract.
• support_handoff event forwarding from JavaScript to native.
• WebView URL policy split between in-app browsing and system browser.

Contradictions and Caveats

• Samples still document legacy command contract ({"cmd":"openURL","value":"..."}) while marking it deprecated.
• Naming in sample classes uses "LiveSDK" and "Virtual Assistant" while docs use "Virtual Agent".
• Treat sample repos as implementation patterns, not canonical naming source.

Versioning and Drift

Naming Drift

• Current docs and product naming: Virtual Agent.
• Sample repo naming still includes legacy terms: virtual-assistant, liveSDK, ZMLiveSDKWebviewController.
• Integration code should follow current docs semantics while mapping legacy symbol names from samples.

Deprecated or Legacy Patterns

• openURL command JSON payload is marked deprecated in 2024 sample code comments.
• Preferred URL launch patterns:
• DOM anchor links with target="_blank".
• window.open() in JavaScript context.
• Native URL interception in WebView delegates.

Stability Strategy

• Wrap SDK calls behind readiness gates.
• Centralize bridge constants so command/event renames are isolated.
• Keep fallback path for legacy keys only where backward compatibility is required.

Virtual Agent 5-Minute Runbook

1. Credentials and Product Access

• Confirm Virtual Agent license is active.
• Confirm campaign or entry ID exists and is published.
• Confirm API key and environment (us01 or eu01) are correct.

2. Browser or WebView Readiness

• Verify CSP allows Zoom SDK script, websocket, media, and wasm execution.
• Verify no blocker/proxy is stripping zcc-sdk.js.
• For WebView, verify JavaScript is enabled.

3. Lifecycle Order

• Load SDK script.
• Wait for zoomCampaignSdk:ready or waitForReady().
• Register event handlers.
• Call open() / show() only after readiness.

4. Native Bridge (Android/iOS)

• Inject window.zoomCampaignSdk.native on readiness.
• Wire exitHandler, commonHandler, and support_handoff callbacks.
• Verify URL policy (target="_blank", window.open) is implemented.

5. Drift Check

• Validate docs naming (Virtual Agent) vs sample naming (Virtual Assistant / LiveSDK).
• Treat openURL command path as legacy/deprecated and prefer DOM links or window.open.

High-Level Scenarios

1. Website Campaign Entry

• Use campaign embed snippet to control initial bot routing without code redeploys.
• Use show()/hide()/open()/close() for page-specific behavior.

2. Native Mobile Wrapper (Android/iOS)

• Host campaign URL in WebView/WKWebView.
• Inject customer context (language, name, profile fields).
• Route exit and handoff messages into native app state.

3. Bot-to-Agent Escalation

• Listen for support_handoff payload.
• Persist payload to backend for CRM/ticket enrichment.
• Route customer into live support workflow.

4. URL Navigation Governance

• Open trusted links inside app.
• Send external links to system browser when policy requires.
• Handle target="_blank" and window.open explicitly.

5. Knowledge-Base Sync Pipeline

• Use web sync for crawlable documentation.
• Use custom API connector for external CMS pull/push synchronization.
• Re-run sync on content release cadence.

Common Drift and Breaks

SDK Not Ready

Symptoms:

• window.zoomCampaignSdk is undefined.

Fix:

• Register logic only after zoomCampaignSdk:ready.
• Prefer waitForReady() when available.

Campaign Configured but Not Showing

Checks:

• Confirm campaign targeting includes mobile when using Android/iOS WebView.
• Validate style/config API network responses.

Subdomain/Login Failures

Symptoms:

• Login fails due to subdomain connection issue.

Fix:

• Verify subdomain allowlist and environment settings in Virtual Agent preferences.

Script Tag Loads Inconsistently

Cause:

• defer can break execution order in certain third-party-link flows.

Fix:

• Remove defer or use async based on page lifecycle.

Deprecated URL Command Usage

Symptoms:

• Legacy openURL command path behaves unpredictably across versions.

Fix:

• Use DOM links (target="_blank") or window.open and explicit native navigation handlers.

Lifecycle and Events (Web)

Lifecycle

1. Inject script with API key and env. 2. Wait for zoomCampaignSdk:ready or waitForReady(). 3. Register event listeners. 4. Execute control calls (open, close, show, hide, endChat). 5. Optionally refresh user variables via updateUserContext(). 6. Remove listeners during page teardown.

Event Surface

• open
• close
• show
• hide
• engagement_started
• engagement_ended

Method Surface

• close()
• endChat()
• hide()
• show()
• ChangeCampaign(id, channel?)
• updateUserContext()
• waitForInit()
• waitForReady()

Campaign and Entry Patterns

Campaign-First Pattern (Recommended)

<script data-apikey="YOUR_API_KEY" src="https://us01ccistatic.zoom.us/us01cci/web-sdk/zcc-sdk.js"></script>
<script>
window.addEventListener('zoomCampaignSdk:ready', () => {
  window.zoomCampaignSdk.show();
  window.zoomCampaignSdk.on('engagement_started', () => {
    console.log('engagement started');
  });
});
</script>

Runtime User Context Refresh

window.zoomCampaignSdkConfig = {
  env: 'us01',
  apikey: 'YOUR_API_KEY',
  firstName: 'Ada',
  email: 'ada@example.com'
};

window.addEventListener('zoomCampaignSdk:ready', async () => {
  if (window.zoomCampaignSdk.waitForReady) {
    await window.zoomCampaignSdk.waitForReady();
  }
  window.zoomCampaignSdk.updateUserContext();
});

Entry ID Fallback Pattern

Use entry ID only when your flow requires pre-chat data collection that cannot be handled in campaign configuration.

Web Reference Map

Core Docs

• Get started: https://developers.zoom.us/docs/virtual-agent/web/get-started/
• Chat embed: https://developers.zoom.us/docs/virtual-agent/web/chat/
• Campaign controls: https://developers.zoom.us/docs/virtual-agent/web/campaigns/
• SDK reference: https://developers.zoom.us/docs/virtual-agent/web/reference/

Operational Notes

• Campaign mode supports central admin routing and lower app-code churn.
• Entry ID mode can increase friction and should be selective.
• Keep script host, CSP, and environment alignment (us01/eu01) in preflight checks.

Web Common Issues

window.zoomCampaignSdk Is Undefined

• Confirm script URL is reachable and not blocked.
• Confirm initialization completed before method calls.

CSP Blocks SDK

• Add CSP directives for script/connect/media/font/image paths required by Zoom SDK.
• Re-test with browser console open for wasm or websocket policy errors.

Campaign Not Triggering

• Validate campaign targeting rules and page conditions.
• Inspect network calls and config/style responses.

Third-Party Link Behavior

• Avoid fragile defer script behavior when startup triggers external links.
• Prefer explicit handling for target="_blank" and window.open flows.