Build Zoom Contact Center App

Zoom Contact Center SDK - Android

Official docs:

• https://developers.zoom.us/docs/contact-center/android/
• https://marketplacefront.zoom.us/sdk/contact/android/index.html

Quick Links

1. concepts/sdk-lifecycle.md 2. examples/service-patterns.md 3. references/android-reference-map.md 4. troubleshooting/common-issues.md

SDK Surface Summary

• SDK manager: ZoomCCInterface
• Channel services:
• getZoomCCChatService()
• getZoomCCVideoService()
• getZoomCCZVAService()
• getZoomCCScheduledCallbackService()
• Campaign support via web campaign service and campaign metadata.

Hard Guardrails

• Initialize SDK in Application.onCreate.
• Use ZoomCCItem to define channel + identifiers.
• Use entryId for chat/video/ZVA.
• Use apiKey for scheduled callback and campaign mode.
• Release services on teardown.

Common Chains

• Contact Center app and engagement context: ../../zoom-apps-sdk/SKILL.md
• Contact Center API automation: ../../rest-api/SKILL.md

Operations

• RUNBOOK.md - 5-minute preflight and debugging checklist.

Android SDK Lifecycle

Startup

1. Initialize once in Application.onCreate. 2. Optionally set/update context user name before channel launch.

Channel Initialization

1. Get service from ZoomCCInterface. 2. Build ZoomCCItem with:

• sdkType
• entryId or apiKey
• serverType
• campaign fields when needed

3. service.init(item). 4. Add listener(s).

Launch

1. Chat/ZVA:

• call login() then fetchUI().

2. Video:

• configure preview/auto-join options as needed.
• call fetchUI(); login is typically internal for video flow.

3. Scheduled callback:

• init with apiKey.
• fetchUI().

End and Cleanup

1. End engagement (endChat / endVideo) when needed. 2. logoff() when you need to stop callbacks. 3. releaseZoomCCService(key) in teardown paths (onDestroy).

Campaign Mode

1. Request campaigns with campaign API key. 2. Select channel from campaign metadata. 3. Reinitialize service using campaign-mode item. 4. Release or end conflicting channel services before switch.

Android Service Patterns

Chat Pattern

val service = ZoomCCInterface.getZoomCCChatService()
service.init(
    ZoomCCItem(
        entryId = chatEntryId,
        sdkType = ZoomCCIInterfaceType.CHAT,
        serverType = CCServerType.CCServerWWW
    )
)
service.addListener(object : ZoomCCChatListener {
    override fun unreadMsgCountChanged(count: Int) {}
    override fun onClientEvent(event: ClientEvent) {}
    override fun onEngagementEnd(engagementId: String) {}
    override fun onEngagementStart(engagementId: String) {}
    override fun onLoginStatus(status: IMStatus?) {}
    override fun onError(error: Int, detail: Long, description: String) {}
})
service.login()
service.fetchUI()

Video Pattern

val service = ZoomCCInterface.getZoomCCVideoService()
service.init(
    ZoomCCItem(
        entryId = videoEntryId,
        sdkType = ZoomCCIInterfaceType.VIDEO,
        serverType = CCServerType.CCServerWWW
    )
)
service.setVideoPreviewOption(VideoPreviewOption.ZmCCVideoPreviewOptionDefault)
service.setAutoJoinWhenVideoCreated(false)
service.setUseBackwardFacingCameraByDefault(false)
service.addListener(object : ZoomCCVideoListener {})
service.fetchUI()

Scheduled Callback Pattern

val service = ZoomCCInterface.getZoomCCScheduledCallbackService()
service.init(
    ZoomCCItem(
        apiKey = callbackApiKey,
        sdkType = ZoomCCIInterfaceType.SCHEDULED_CALLBACK,
        serverType = CCServerType.CCServerWWW
    )
)
service.fetchUI()

Cleanup Pattern

override fun onDestroy() {
    ZoomCCInterface.releaseZoomCCService(chatEntryId)
    ZoomCCInterface.releaseZoomCCService(videoEntryId)
    ZoomCCInterface.releaseZoomCCService(callbackApiKey)
    super.onDestroy()
}

Android Reference Map

Primary reference:

• https://marketplacefront.zoom.us/sdk/contact/android/index.html

Core Types

• ZoomCCInterface
• ZoomCCItem
• ZoomCCContext
• ZoomCCService
• ZoomCCChatService
• ZoomCCVideoService
• ZoomCCScheduledCallbackService

Listener Types

• ZoomCCServiceListener
• ZoomCCChatListener
• ZoomCCVideoListener

Enums

• ZoomCCIInterfaceType
• ClientEvent
• IMStatus
• CCServerType
• VideoPreviewOption

Common Methods

• SDK init/context:
• ZoomCCInterface.init(...)
• ZoomCCInterface.setContext(...)
• service factory:
• getZoomCCChatService()
• getZoomCCVideoService()
• getZoomCCZVAService()
• getZoomCCScheduledCallbackService()
• service lifecycle:
• init(item), login(), logoff(), fetchUI()
• engagement control:
• endChat(), endVideo()
• release:
• releaseZoomCCService(key)

Deprecation Notes

• Review deprecated.html in each SDK version package.
• Keep runtime guards for enum/value additions and optional callbacks.

Contact Center Android 5-Minute Preflight Runbook

Use this before deep debugging.

Skill Doc Standard Note

• Skill entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SDK/API names can drift by version; validate current names against docs/raw-docs before release.

1) Confirm Integration Surface

• Confirm channel target and integration mode for Android.
• Contact Center app path and web embed path have different lifecycle rules.
• For mobile SDKs, verify native service lifecycle and listener registration order.

2) Confirm Required Credentials

• entryId for chat/video/ZVA entry points.
• apiKey for scheduled callback and campaign/tag use cases.
• If in-client app behavior is needed, verify Zoom App credentials and required scopes.

3) Confirm Lifecycle Order

1. Initialize SDK context early. 2. Get channel service and register listeners/delegates before actions. 3. Authenticate/login where required. 4. Start/fetch channel UI and handle engagement status transitions.

4) Confirm Event/State Handling

• Track state by engagementId; do not assume single engagement forever.
• Handle context-switch events without losing draft/chat workflow state.
• Keep service/channel state isolated per active engagement.

5) Confirm Cleanup + Upgrade Posture

• End channel session and release service resources cleanly.
• Forward app lifecycle callbacks for iOS integrations.
• Re-check release notes for renamed/deprecated methods before upgrades.

6) Quick Probes

• Engagement context/status APIs return valid values.
• Start/end flow works once end-to-end for target channel.
• Listener callbacks fire on switch/end events without stale state.

7) Fast Decision Tree

• UI does not open -> invalid entryId/apiKey or missing init/listener sequence.
• Events missing -> listener registered too late or detached unexpectedly.
• Rejoin/resume fails -> lifecycle callbacks or deep-link/scheme config mismatch.

8) Source Checkpoints

Official docs

• https://developers.zoom.us/docs/contact-center/android/
• https://marketplacefront.zoom.us/sdk/contact/android/index.html

Raw docs in repo

• raw-docs/developers.zoom.us/docs/contact-center/android/
• raw-docs/marketplacefront.zoom.us/sdk/contact/android/

Android Common Issues

SDK Works Inconsistently Across Screens

Cause:

• SDK initialized too late.

Fix:

• Initialize in Application.onCreate.

NoClassDefFoundError / viewBinding Errors

Cause:

• Missing expected dependencies or view binding configuration.

Fix:

• Match SDK package module requirements.
• Ensure build config aligns with current SDK release notes.

Video/Chat UI Does Not Open

Cause:

• Wrong identifier type in ZoomCCItem.

Fix:

• entryId for chat/video/ZVA.
• apiKey for scheduled callback/campaign.

Events Not Firing

Cause:

• Listener attached after service launch or removed early.

Fix:

• Add listeners before fetchUI.

Rejoin Link Opens Browser But Not App

Cause:

• Deep-link host/scheme mismatch.

Fix:

• Align Android manifest intent filters with generated rejoin URL format.

Contact Center Architecture and Lifecycle

This document defines a stable architecture pattern that works across Contact Center app, web, and mobile integrations.

Architecture Layers

1. Integration Surface

• Zoom Contact Center App (Zoom client embedded webview).
• Web SDK/Campaign SDK on external sites.
• Android/iOS native SDK.

2. Engagement State Layer

• Current engagementId.
• Engagement status (start, hold, resume, end).
• Engagement-scoped draft data.

3. Channel Service Layer

• Chat.
• Video.
• ZVA.
• Scheduled Callback.

4. Persistence Layer

• Transient per-engagement state cache (frontend local storage or backend session store).
• Optional backend persistence for long-running workflows and compliance logging.

Canonical Lifecycle

1. Initialize context. 2. Determine active engagement context. 3. Build/init channel service/client. 4. Register callbacks before launching UI. 5. Start channel view. 6. Process status/context events. 7. End and cleanup.

Context-Switching Contract

• Treat engagementId as the primary state key.
• Never assume a single engagement in memory for messaging channels.
• Restore state on each engagement context change.
• Clear or archive engagement state only when end-state logic is complete.

Event-Driven Contract

• Do not poll as a primary strategy.
• Subscribe early and keep handlers idempotent.
• Handle out-of-order or repeated events safely.

Campaign Mode Pattern

1. Fetch campaigns with campaign API key. 2. Pick channel from translatedCampaignChannels. 3. Create channel item with useCampaignMode=true. 4. Launch service UI. 5. Release conflicting channel services when switching channels.

Security and Identity

• Use explicit user/session identity refresh paths (authorize, getAppContext) for Contact Center app scenarios.
• For PWA flows, do not depend on x-zoom-app-context header.
• Keep OAuth and app context decryption on backend where possible.

iOS SDK Lifecycle

Context Initialization

1. Create ZoomCCContext. 2. Configure user name, cache folder, and optional share settings. 3. Set context on ZoomCCInterface.sharedInstance().

Service Initialization Pattern

1. Build ZoomCCItem. 2. Select channel type:

• .chat
• .video
• .ZVA
• .scheduledCallback

3. Populate entryId or apiKey depending on channel. 4. Get service instance. 5. Set delegate. 6. Call initialize(with:). 7. Call login() where required. 8. fetchUI and push returned view controller.

Lifecycle Bridging

Forward these app delegate callbacks:

• applicationDidBecomeActive -> appDidBecomeActive
• applicationWillResignActive -> appWillResignActive
• applicationDidEnterBackground -> appDidEnterBackgroud
• applicationWillTerminate -> appWillTerminate

Rejoin Flow

1. Configure app URL scheme and admin rejoin URL. 2. Forward open url callback to rejoin handler. 3. Call video service rejoin API with prepared ZoomCCItem. 4. Push returned view controller in completion block.

Cleanup

• End service-specific engagement methods:
• endChat
• endVideo
• endScheduledCallback
• Use service logout / uninitialize patterns when needed by flow design.

iOS Service Patterns

Context Setup

let context = ZoomCCContext()
context.cacheFolder = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true).first!
context.userName = userName
context.domainType = .US01
ZoomCCInterface.sharedInstance().context = context

Chat Pattern

let item = ZoomCCItem()
item.sdkType = .chat
item.entryId = chatEntryId

let chat = ZoomCCInterface.sharedInstance().chatService()
chat.chatDelegate = self
if chat.status == .initial {
    chat.initialize(with: item)
    chat.login()
}
chat.fetchUI { vc in
    if let vc { self.navigationController?.pushViewController(vc, animated: true) }
}

Video Pattern

let item = ZoomCCItem()
item.sdkType = .video
item.entryId = videoEntryId

let video = ZoomCCInterface.sharedInstance().videoService()
video.videoDelegate = self
if video.status == .initial {
    video.initialize(with: item)
}
video.fetchUI { vc in
    if let vc { self.navigationController?.pushViewController(vc, animated: true) }
}

Scheduled Callback Pattern

let item = ZoomCCItem()
item.sdkType = .scheduledCallback
item.apiKey = callbackApiKey

let scheduled = ZoomCCInterface.sharedInstance().scheduledCallbackService()
scheduled.scheduledCallbackDelegate = self
if scheduled.status == .initial {
    scheduled.initialize(with: item)
}
scheduled.fetchUI { vc in
    if let vc { self.navigationController?.pushViewController(vc, animated: true) }
}

Rejoin Pattern

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    return rootVC.handleRejoinVideoOpenURL(url)
}

iOS Reference Map

Primary references:

• https://marketplacefront.zoom.us/sdk/contact/ios/index.html
• SDK headers packaged in iOS SDK zip (ZoomCCInterface.h)

Core Types

• ZoomCCInterface
• ZoomCCContext
• ZoomCCItem
• ZoomCCCampaignInfo

Service Protocols

• ZoomCCService
• ZoomCCChatService
• ZoomCCVideoService
• ZoomCCScheduledCallbackService

Delegate Protocols

• ZoomCCServiceDelegate
• ZoomCCChatServiceDelegate
• ZoomCCAppLifecyleDelegate

Key Methods

• Interface:
• sharedInstance
• chatService
• zvaService
• videoService
• scheduledCallbackService
• getCampaigns
• Service lifecycle:
• initializeWithItem
• login
• logout
• fetchUI
• Video:
• handleRejoinVideoOpenURL:item:videoDelegate:complete:

Deprecation Note

• onService:error:detail: is deprecated.
• Use onService:error:detail:description:.

Contact Center iOS 5-Minute Preflight Runbook

Use this before deep debugging.

Skill Doc Standard Note

• Skill entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SDK/API names can drift by version; validate current names against docs/raw-docs before release.

1) Confirm Integration Surface

• Confirm channel target and integration mode for iOS.
• Contact Center app path and web embed path have different lifecycle rules.
• For mobile SDKs, verify native service lifecycle and listener registration order.

2) Confirm Required Credentials

• entryId for chat/video/ZVA entry points.
• apiKey for scheduled callback and campaign/tag use cases.
• If in-client app behavior is needed, verify Zoom App credentials and required scopes.

3) Confirm Lifecycle Order

1. Initialize SDK context early. 2. Get channel service and register listeners/delegates before actions. 3. Authenticate/login where required. 4. Start/fetch channel UI and handle engagement status transitions.

4) Confirm Event/State Handling

• Track state by engagementId; do not assume single engagement forever.
• Handle context-switch events without losing draft/chat workflow state.
• Keep service/channel state isolated per active engagement.

5) Confirm Cleanup + Upgrade Posture

• End channel session and release service resources cleanly.
• Forward app lifecycle callbacks for iOS integrations.
• Re-check release notes for renamed/deprecated methods before upgrades.

6) Quick Probes

• Engagement context/status APIs return valid values.
• Start/end flow works once end-to-end for target channel.
• Listener callbacks fire on switch/end events without stale state.

7) Fast Decision Tree

• UI does not open -> invalid entryId/apiKey or missing init/listener sequence.
• Events missing -> listener registered too late or detached unexpectedly.
• Rejoin/resume fails -> lifecycle callbacks or deep-link/scheme config mismatch.

8) Source Checkpoints

Official docs

• https://developers.zoom.us/docs/contact-center/ios/
• https://marketplacefront.zoom.us/sdk/contact/ios/index.html

Raw docs in repo

• raw-docs/developers.zoom.us/docs/contact-center/ios/
• raw-docs/marketplacefront.zoom.us/sdk/contact/ios/

iOS Common Issues

Service Starts But View Never Appears

Cause:

• Missing fetchUI handling or wrong navigation presentation path.

Fix:

• Ensure returned view controller is pushed/presented on main thread.

App Background/Foreground Breaks Session

Cause:

• App lifecycle callbacks not forwarded to SDK.

Fix:

• Wire app delegate lifecycle methods to ZoomCCInterface.

Rejoin URL Arrives But Rejoin Fails

Cause:

• URL scheme mismatch or context not initialized.

Fix:

• Verify URL types config, rejoin URL settings, and context setup before calling rejoin API.

Duplicate or Stale Channel Sessions

Cause:

• Previous service instance left active during channel switches.

Fix:

• End current engagement and rebuild service item when changing channel/campaign context.

Error Callback Signature Drift

Cause:

• Implemented only deprecated callback signature.

Fix:

• Implement onService:error:detail:description: and keep compatibility wrappers as needed.

Zoom Contact Center Environment Variables

Standard .env keys

Runtime-only values

• ZOOM_ACCESS_TOKEN
• Contact/session IDs issued by Contact Center runtime APIs

Notes

• Contact Center implementations often mix OAuth credentials with flow/campaign keys.
• Keep OAuth secrets and campaign keys out of client-side source control.

Forum-Derived Top Questions (Contact Center)

Use this as a checklist of the most common recent Developer Forum asks for Zoom Contact Center integrations.

Fast Routing Questions (Ask First)

• Surface: Contact Center app in Zoom client, web SDK/campaign embed, Smart Embed, or REST API workflow.
• Runtime: web vs Android vs iOS and exact SDK version.
• Auth context: app type, scopes, token owner, and Contact Center admin role.
• Resource target: queue/flow/engagement IDs and expected channel (voice, video, chat, callback).
• Failure proof: exact endpoint/event, full response code/message, and one representative payload.

Smart Embed Login/Origin Problems

Common asks:

• Login popup completes but embed never receives session.
• Hosted environment fails while local HTML test works.

Answer pattern:

• Verify allowed domain configuration exactly matches production origin.
• Validate origin usage and postMessage contract assumptions.
• Check iframe/sandbox/CSP restrictions for hosted environments.
• Reproduce with a minimal page (embed only) to isolate app-layer interference.

Token Works for Phone But Contact Center API Returns 401

Common asks:

• Same bearer token can call Phone endpoints but Contact Center endpoints return invalid token.

Answer pattern:

• Confirm Contact Center scopes are on the active token (not only app config).
• Confirm requester has Contact Center admin permissions in target account.
• Confirm account context did not drift (owner/admin reassignment can break behavior).
• Regenerate token after any scope/role changes.

Event Gaps and State-Change Confusion

Common asks:

• contact_center.user_status_changed or engagement events appear missing.
• Documented event name does not fire as expected in a given lifecycle.

Answer pattern:

• Attach listeners before channel/session start.
• Verify event coverage for the specific channel and engagement phase.
• Confirm network/security layers are not blocking webhook deliveries.
• Add reconciliation logic instead of assuming every state transition emits one event.

Recordings and Transcripts Edge Cases

Common asks:

• Recording rows exist but media/transcript is unavailable.
• Transcript download fails or payload differs from expectations.

Answer pattern:

• Check recording duration/status before download attempts.
• Handle not-ready and no-recording states explicitly.
• Retry with bounded backoff for newly completed engagements.
• Keep fallback handling for empty/partial recording metadata.

Analytics Pagination Repeats First Page

Common asks:

• next_page_token loops the same records in historical analytics endpoints.

Answer pattern:

• Keep all filter params stable while paging.
• Use token exactly as returned; do not mutate sort/filter inputs mid-stream.
• Add duplicate-page detection and stop conditions in client code.

Data Availability Boundaries

Common asks:

• Access to in-progress chat messages or other live interaction internals.

Answer pattern:

• Distinguish near-real-time events from post-engagement reporting APIs.
• Set expectations early when an in-progress data surface is unavailable.
• Design workflows around available lifecycle events and finalized engagement data.

Samples Validation Summary

This summary captures lifecycle and architecture checks against these references:

• Web:
• https://github.com/zoom/ZCC-Zoom-App-Advanced-Sample
• https://github.com/zoom/zcc-javascript-quickstart
• https://github.com/zoom/zcc-nextjs-sample
• iOS package: ios-zccsdk-5.2.0.zip
• Android package: android-zccsdk-5.2.0.zip

Confirmed Lifecycle Patterns

1. Contact Center App (Zoom Apps SDK):

• Configure capabilities.
• Query engagement context/status.
• Subscribe to engagement change events.
• Persist state by engagementId.

2. Android Native:

• Initialize in Application.onCreate.
• Service init with ZoomCCItem.
• Use fetchUI to present channel.
• logoff and releaseZoomCCService on cleanup.

3. iOS Native:

• Set ZoomCCInterface.sharedInstance().context.
• Initialize service with item.
• Use fetchUI to present.
• Forward app lifecycle callbacks to SDK.
• Use rejoin handler path for video reconnect.

Contradictions and Drift Signals

• Some docs show simplified service.init("EntryId") signatures while current references emphasize item-based initialization.
• iOS deprecated error callback still appears in older sample/docs.
• Some public sample manifests contain values that conflict with expected Contact Center embedding configuration and should be reviewed per environment.
• Scraped reference pages include parser artifacts (TODO/error pages) and should not be treated as canonical API surfaces.

Operational Guidance

• Treat samples as architecture guidance, not immutable source of truth.
• Resolve conflicts in this order:

1. Current official docs. 2. Current platform API reference. 3. Latest shipped SDK headers/binaries. 4. Samples.

Versioning and Compatibility Notes

Minimum Version Enforcement

• Zoom enforces SDK minimum versions quarterly.
• Enforcement windows are announced with advance notice.
• Older SDKs can stop functioning in production even if code has not changed.

Practical Policy

1. Track SDK version in runtime telemetry. 2. Maintain a scheduled upgrade cadence. 3. Validate critical flows every release:

• launch/init
• engagement events
• channel open/close
• rejoin (mobile)

Known Drift Patterns

• API shape drift between docs and generated references.
• Legacy snippets showing old method signatures.
• Event naming/style differences between product surfaces.
• Deprecated callbacks preserved for backward compatibility but replaced in newer signatures.

iOS Notable Deprecation

• onService:error:detail: is deprecated.
• Prefer onService:error:detail:description:.

Smart Embed Version Note

• Smart Embed v3 is the forward path in docs.
• Maintain version-gated integration code if your account still has older embed behavior.

Defensive Design

• Feature-detect methods/events before calling them.
• Keep adapters between your domain model and SDK payloads.
• Avoid hard-coding assumptions about optional fields.

Contact Center 5-Minute Preflight Runbook

Use this before deep debugging. It catches the most common Zoom Contact Center integration failures quickly.

Skill Doc Standard Note

• Skill entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SKILL.md is a navigation convention for larger skill docs.

1) Confirm Integration Path

• Contact Center app inside Zoom client: use Zoom Apps SDK APIs/events (getEngagementContext, onEngagementStatusChange, etc.).
• Website embed: use Contact Center web SDK/campaign script path.
• Native mobile app: use Android/iOS Contact Center SDK binaries and service lifecycle.

Wrong path is the top source of confusion.

2) Confirm Required Credentials

• entryId for chat/video/ZVA channels.
• apiKey for scheduled callback and campaign/web-tag scenarios.
• If building a Contact Center app in Zoom client, validate app credentials and OAuth setup in Marketplace.

3) Confirm Lifecycle Order

Common native/mobile order: 1. Initialize SDK context early. 2. Get service instance. 3. Initialize service with ZoomCCItem. 4. Register listener/delegate. 5. login() where required (typically chat/ZVA). 6. fetchUI() to present the channel view.

Web app path: 1. zoomSdk.config(...) 2. getEngagementContext() and getEngagementStatus() 3. subscribe to onEngagementContextChange and onEngagementStatusChange 4. persist state keyed by engagementId

4) Confirm Context Switching Behavior

• A single app instance can receive multiple engagement contexts.
• Persist draft/workflow state by engagementId.
• Do not assume only one active engagement for chat/SMS/email workflows.

5) Confirm Cleanup Semantics

• End action (endChat, endVideo, endScheduledCallback) is not the same as service release.
• Apply platform-specific cleanup (logout/logoff, release/uninitialize APIs).
• On iOS, forward app lifecycle callbacks (appDidBecomeActive, appWillTerminate, etc.) to ZoomCCInterface.

6) Version + Drift Checks

• Zoom enforces minimum SDK versions quarterly (first weekend of February, May, August, November).
• Re-check docs and changelog before release; naming and signatures can drift.
• Watch deprecations:
• iOS onService:error:detail: is deprecated in favor of onService:error:detail:description:.

7) Quick Probes

• App context/status APIs return valid values.
• Engagement events fire when agent switches engagements.
• Chat/video/scheduled callback can be started and ended once each without stale state.
• No CSP or domain allow-list blocks for web integrations.

8) Fast Decision Tree

• No engagement data in Contact Center app -> missing SDK config capabilities or wrong runtime context.
• Channel UI does not open -> invalid entryId/apiKey, missing init, or wrong service/channel mapping.
• Events not firing on switch/end -> listeners not attached early enough or removed incorrectly.
• Rejoin fails on mobile -> deep-link/scheme configuration mismatch.

High-Level Scenarios

1. Agent Notes App in Contact Center

Goal:

• Agent writes notes that follow engagement context switching.

Flow: 1. config Zoom Apps SDK with engagement capabilities. 2. Load getEngagementContext + getEngagementStatus. 3. Store notes by engagementId. 4. On onEngagementContextChange, swap UI state to selected engagement. 5. On onEngagementStatusChange end, finalize or clear engagement draft.

2. Web Chat Campaign Launch

Goal:

• Product team controls targeting in admin without code redeploy.

Flow: 1. Add campaign web tag script. 2. Wait for zoomCampaignSdk:ready. 3. Programmatically open/show/hide/close as needed. 4. Listen for engagement events for analytics and CRM writes.

3. Mobile Chat and Video with Native SDK

Goal:

• Customer mobile app can launch chat/video and recover from interruptions.

Flow: 1. Initialize SDK context in app startup. 2. Build ZoomCCItem for channel. 3. Initialize service, attach delegates/listeners, and launch UI. 4. Handle disconnect/rejoin links for video. 5. End flow and release service resources.

4. Campaign-Mode Channel Router

Goal:

• Runtime selection of chat/video/ZVA/scheduled callback per campaign.

Flow: 1. Fetch campaigns by API key. 2. Inspect campaign channels. 3. Build channel-specific item with campaign mode. 4. Release previous conflicting service before opening new channel.

5. Smart Embed CRM Integration

Goal:

• Embed Contact Center softphone in CRM with screen-pop and contact lookup.

Flow: 1. Load Smart Embed iframe. 2. Handle postMessage events (zcc-init-config-request, search, resize, engagement events). 3. Return contact search results and route screen-pop in CRM. 4. Keep feature flags aligned with Smart Embed version path.

Common Drift and Breaks

Symptom: Engagement Context Missing

Likely causes:

• App is not running in Contact Center context.
• Missing SDK capabilities in config.
• Identity/context token path is incomplete.

Checks: 1. Confirm running context. 2. Confirm capabilities include engagement APIs/events. 3. Confirm app manifest and feature toggles.

Symptom: Campaign SDK Methods Throw

Likely causes:

• Calling methods before zoomCampaignSdk:ready.
• Invalid API key or missing campaign configuration.
• Script blocked by CSP/ad-blockers/tag-manager path.

Checks: 1. Add ready gate before method calls. 2. Validate key/env and script URL. 3. Validate CSP/domain allow lists.

Symptom: Native Service Not Responding

Likely causes:

• SDK init executed too late.
• Wrong channel item (entryId vs apiKey mismatch).
• Listeners/delegates attached after service start.

Checks: 1. Move init earlier in app lifecycle. 2. Validate item/channel pairing. 3. Register listeners before fetchUI.

Symptom: Rejoin Flow Fails

Likely causes:

• Deep link scheme/host mismatch.
• Rejoin URL or web relay page not configured.
• App lifecycle hooks/context not initialized.

Checks: 1. Verify platform URL/deep link configuration. 2. Verify admin rejoin settings. 3. Verify rejoin handler wiring.

Symptom: Behavior Changed After Release

Likely causes:

• Minimum version enforcement date reached.
• Deprecated callback removed or changed.
• New SDK defaults in channel behavior.

Checks: 1. Confirm SDK version in production. 2. Review changelog/deprecation notes. 3. Add adapter guards for optional fields/methods.

Web Lifecycle and Event Model

Contact Center App Runtime (Zoom Client)

1. Configure SDK capabilities. 2. Read running context. 3. Read engagement context/status. 4. Subscribe to:

• onEngagementContextChange
• onEngagementStatusChange
• optional variable change events

5. Maintain engagement-scoped state.

Web Campaign SDK Runtime

1. Load script with API key. 2. Wait for zoomCampaignSdk:ready. 3. Call methods:

• open
• close
• show
• hide
• endChat

4. Subscribe/unsubscribe to SDK events.

Video Client Runtime

1. Create client. 2. Initialize with entry identifier and optional metadata. 3. Start video. 4. Handle video-start and video-end events.

Smart Embed Runtime

1. Load Smart Embed iframe. 2. Listen for message events from iframe. 3. Respond to init/search/control requests. 4. Map engagement and contact data to CRM/app entities.

State Strategy

• Key all session data by engagementId.
• Keep event handlers re-entrant and idempotent.
• Treat end status as cleanup boundary.

Web Example: Engagement-Aware State

await zoomSdk.config({
  version: "0.16.0",
  capabilities: [
    "getRunningContext",
    "getEngagementContext",
    "getEngagementStatus",
    "onEngagementContextChange",
    "onEngagementStatusChange",
  ],
});

const stateByEngagement = new Map();
let currentEngagementId = "";

function ensureState(id) {
  if (!stateByEngagement.has(id)) {
    stateByEngagement.set(id, { notes: "", formDraft: {} });
  }
  return stateByEngagement.get(id);
}

async function hydrate() {
  const [ctx, status] = await Promise.all([
    zoomSdk.callZoomApi("getEngagementContext"),
    zoomSdk.callZoomApi("getEngagementStatus"),
  ]);
  currentEngagementId = ctx?.engagementContext?.engagementId || "";
  if (currentEngagementId) ensureState(currentEngagementId);
  render(currentEngagementId, status?.engagementStatus?.state);
}

zoomSdk.addEventListener("onEngagementContextChange", (evt) => {
  currentEngagementId = evt?.engagementContext?.engagementId || "";
  if (currentEngagementId) ensureState(currentEngagementId);
  render(currentEngagementId);
});

zoomSdk.addEventListener("onEngagementStatusChange", (evt) => {
  const state = evt?.engagementStatus?.state;
  if (state === "end" && currentEngagementId) {
    stateByEngagement.delete(currentEngagementId);
  }
  render(currentEngagementId, state);
});

hydrate();

Campaign SDK Ready Gate

window.addEventListener("zoomCampaignSdk:ready", () => {
  if (!window.zoomCampaignSdk) return;
  window.zoomCampaignSdk.show();
});

Web Reference Map

Primary docs:

• https://developers.zoom.us/docs/contact-center/web/get-started/
• https://developers.zoom.us/docs/contact-center/web/chat/
• https://developers.zoom.us/docs/contact-center/web/video/
• https://developers.zoom.us/docs/contact-center/web/campaigns/
• https://developers.zoom.us/docs/contact-center/web/sdk-reference/
• https://developers.zoom.us/docs/contact-center/smart-embed/

Engagement APIs/Events (Contact Center App)

• getEngagementContext
• getEngagementStatus
• onEngagementContextChange
• onEngagementStatusChange
• onEngagementVariableValueChange

Campaign SDK Events

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

Campaign SDK Methods

• open()
• close()
• show()
• hide()
• endChat()
• waitForInit()
• waitForReady()
• updateUserContext()

Video Client Events

• video-start
• video-end
• notification-join-call
• video-click-end
• video-force-end
• task-created

Smart Embed Event Surface

• init/config events (zcc-init-config-request, zcc-init-config-response)
• engagement and channel events
• contact search request/response patterns
• resize and interaction events

Contact Center Web 5-Minute Preflight Runbook

Use this before deep debugging.

Skill Doc Standard Note

• Skill entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SDK/API names can drift by version; validate current names against docs/raw-docs before release.

1) Confirm Integration Surface

• Confirm channel target and integration mode for Web.
• Contact Center app path and web embed path have different lifecycle rules.
• For mobile SDKs, verify native service lifecycle and listener registration order.

2) Confirm Required Credentials

• entryId for chat/video/ZVA entry points.
• apiKey for scheduled callback and campaign/tag use cases.
• If in-client app behavior is needed, verify Zoom App credentials and required scopes.

3) Confirm Lifecycle Order

1. Initialize SDK context early. 2. Get channel service and register listeners/delegates before actions. 3. Authenticate/login where required. 4. Start/fetch channel UI and handle engagement status transitions.

4) Confirm Event/State Handling

• Track state by engagementId; do not assume single engagement forever.
• Handle context-switch events without losing draft/chat workflow state.
• Keep service/channel state isolated per active engagement.

5) Confirm Cleanup + Upgrade Posture

• End channel session and release service resources cleanly.
• Forward app lifecycle callbacks for iOS integrations.
• Re-check release notes for renamed/deprecated methods before upgrades.

6) Quick Probes

• Engagement context/status APIs return valid values.
• Start/end flow works once end-to-end for target channel.
• Listener callbacks fire on switch/end events without stale state.

7) Fast Decision Tree

• UI does not open -> invalid entryId/apiKey or missing init/listener sequence.
• Events missing -> listener registered too late or detached unexpectedly.
• Rejoin/resume fails -> lifecycle callbacks or deep-link/scheme config mismatch.

8) Source Checkpoints

Official docs

• https://developers.zoom.us/docs/contact-center/web/
• https://developers.zoom.us/docs/contact-center/web/sdk-reference/

Raw docs in repo

• raw-docs/developers.zoom.us/docs/contact-center/web/

Web Common Issues

zoomCampaignSdk Is Undefined

Cause:

• Calls happen before readiness event.

Fix:

• Wait for zoomCampaignSdk:ready before calling SDK methods.

Widget Does Not Load

Cause:

• CSP or domain allow-list blocks script/network access.

Fix:

• Update CSP headers and Marketplace domain allow list entries.

App Context Header Missing in PWA

Cause:

• PWA path does not provide x-zoom-app-context header consistently.

Fix:

• Use getAppContext() and backend token decryption flow.

Engagement Data Gets Overwritten

Cause:

• State keyed globally instead of by engagementId.

Fix:

• Persist and restore state per engagement key.

Smart Embed Events Not Received

Cause:

• postMessage listener origin/type filtering missing or incorrect.

Fix:

• Implement strict message handling and respond to required init/search events.