build-zoom-contact-center-app

어떤 스킬인가요?

Zoom Contact Center SDK for Android. Use for native Android chat/video/ZVA/scheduled callback integrations, campaign mode, service lifecycle, and rejoin handling.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# 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

```kotlin
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

```kotlin
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

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

## Cleanup Pattern

```kotlin
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/`

---
name: contact-center/android
description: "Zoom Contact Center SDK for Android. Use for native Android chat/video/ZVA/scheduled callback integrations, campaign mode, service lifecycle, and rejoin handling."
user-invocable: false
triggers:
  - "contact center android"
  - "zcc android"
  - "zoomccinterface android"
  - "zoomccchatservice"
  - "zoomccvideoservice"
  - "releasezoomccservice"
  - "android rejoin"
---

# 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](concepts/sdk-lifecycle.md)
2. [examples/service-patterns.md](examples/service-patterns.md)
3. [references/android-reference-map.md](references/android-reference-map.md)
4. [troubleshooting/common-issues.md](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](../../zoom-apps-sdk/SKILL.md)
- Contact Center API automation: [../../rest-api/SKILL.md](../../rest-api/SKILL.md)

## Operations

- [RUNBOOK.md](RUNBOOK.md) - 5-minute preflight and debugging checklist.

# 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

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

## Chat Pattern

```swift
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

```swift
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

```swift
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

```swift
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/`

---
name: contact-center/ios
description: "Zoom Contact Center SDK for iOS. Use for native iOS chat/video/ZVA/scheduled callback integrations, app lifecycle bridging, rejoin flow, and callback handling."
user-invocable: false
triggers:
  - "contact center ios"
  - "zcc ios"
  - "zoomccinterface ios"
  - "handleRejoinVideoOpenURL"
  - "zoomccservicedelegate"
  - "scheduled callback ios"
---

# Zoom Contact Center SDK - iOS

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

## Quick Links

1. [concepts/sdk-lifecycle.md](concepts/sdk-lifecycle.md)
2. [examples/service-patterns.md](examples/service-patterns.md)
3. [references/ios-reference-map.md](references/ios-reference-map.md)
4. [troubleshooting/common-issues.md](troubleshooting/common-issues.md)

## SDK Surface Summary

- Manager: `ZoomCCInterface.sharedInstance()`
- Context: `ZoomCCContext`
- Items: `ZoomCCItem`
- Services:
- `chatService`
- `zvaService`
- `videoService`
- `scheduledCallbackService`

## Hard Guardrails

- Set `ZoomCCContext` before channel operations.
- Forward app lifecycle calls (`appDidBecomeActive`, `appDidEnterBackgroud`, `appWillResignActive`, `appWillTerminate`).
- Use item-based initialization for channels.
- Keep rejoin URL handling connected to the video service path.

## Common Chains

- Contact Center apps in Zoom client: [../../zoom-apps-sdk/SKILL.md](../../zoom-apps-sdk/SKILL.md)
- OAuth and identity: [../../oauth/SKILL.md](../../oauth/SKILL.md)

## Operations

- [RUNBOOK.md](RUNBOOK.md) - 5-minute preflight and debugging checklist.

# 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

| Variable | Required | Used for | Where to find |
| --- | --- | --- | --- |
| `ZOOM_CLIENT_ID` | Yes (API/OAuth integrations) | OAuth app identity for Contact Center APIs | Zoom Marketplace -> OAuth app -> App Credentials |
| `ZOOM_CLIENT_SECRET` | Yes (API/OAuth integrations) | OAuth token exchange | Zoom Marketplace -> OAuth app -> App Credentials |
| `ZOOM_REDIRECT_URI` | User OAuth flow | OAuth callback URL | Zoom Marketplace -> OAuth redirect/allow list |
| `ZCC_CHAT_ENTRY_ID` | Web/chat entry flows | Contact Center chat entry point routing | Contact Center Admin -> Flows -> Entry Points |
| `ZCC_VIDEO_ENTRY_ID` | Video engagement flows | Contact Center video entry point routing | Contact Center Admin -> Flows -> Entry Points |
| `ZCC_ZVA_ENTRY_ID` | Optional (Virtual Agent) | Virtual agent entry routing | Contact Center Admin -> Flows -> Entry Points |
| `ZCC_CAMPAIGN_API_KEY` | Campaign/web embed mode | Campaign authorization for web embed | Contact Center Admin -> Campaign Management -> Web and In-App -> Embed Web Tag |
| `ZCC_WEB_API_KEY` | Web SDK/embed mode | Client-side Contact Center embed initialization | Contact Center Admin -> Campaign Management -> Web and In-App -> Embed Web Tag |
| `ZCC_SCHEDULED_CALLBACK_API_KEY` | Scheduled callback flows | Callback scheduling authorization | Contact Center campaign/flow callback configuration |

## 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.

---
title: "Forum-Derived Top Questions (Contact Center)"
---

# 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.

---
name: build-zoom-contact-center-app
description: "Reference skill for Zoom Contact Center. Use after routing to a contact-center workflow when implementing app, web, or native integrations; engagement context and state handling; campaigns; callbacks; or version-drift troubleshooting."
triggers:
  - "contact center sdk"
  - "zoom contact center"
  - "zcc"
  - "engagement context"
  - "engagement status"
  - "campaign sdk"
  - "scheduled callback"
  - "getengagementcontext"
  - "onengagementstatuschange"
  - "zoom contact center app"
---

# /build-zoom-contact-center-app

Background reference for Zoom Contact Center integrations across app, web, and native mobile surfaces.

Implementation guidance for Zoom Contact Center across:
- Contact Center apps in the Zoom client (Zoom Apps SDK path)
- Web channel embeds (chat/video/campaign)
- Native mobile SDKs (Android/iOS)

Official docs:
- https://developers.zoom.us/docs/contact-center/
- https://developers.zoom.us/docs/contact-center/web/sdk-reference/
- https://marketplacefront.zoom.us/sdk/contact/android/index.html
- https://marketplacefront.zoom.us/sdk/contact/ios/index.html

## Routing Guardrail

- If the user is building an app inside the Zoom Contact Center desktop client, stay on the Zoom Apps SDK path and use this skill plus `zoom-apps-sdk`.
- If the user is embedding chat/video widgets on a website, route to [web/SKILL.md](web/SKILL.md).
- If the user is integrating native Android or iOS SDK binaries, route to [android/SKILL.md](android/SKILL.md) or [ios/SKILL.md](ios/SKILL.md).
- If the user needs Contact Center call-control or queue APIs, chain with [../rest-api/SKILL.md](../rest-api/SKILL.md).

## Quick Links

Start here:
1. [concepts/architecture-and-lifecycle.md](concepts/architecture-and-lifecycle.md)
2. [scenarios/high-level-scenarios.md](scenarios/high-level-scenarios.md)
3. [references/forum-top-questions.md](references/forum-top-questions.md)
4. [references/versioning-and-compatibility.md](references/versioning-and-compatibility.md)
5. [references/samples-validation.md](references/samples-validation.md)
6. [references/environment-variables.md](references/environment-variables.md)
7. [troubleshooting/common-drift-and-breaks.md](troubleshooting/common-drift-and-breaks.md)
8. [RUNBOOK.md](RUNBOOK.md)

Platform skills:
- [android/SKILL.md](android/SKILL.md)
- [ios/SKILL.md](ios/SKILL.md)
- [web/SKILL.md](web/SKILL.md)

## Documentation Structure

```
contact-center/
├── SKILL.md
├── RUNBOOK.md
├── concepts/
│   └── architecture-and-lifecycle.md
├── scenarios/
│   └── high-level-scenarios.md
├── references/
│   ├── versioning-and-compatibility.md
│   ├── samples-validation.md
│   └── environment-variables.md
├── troubleshooting/
│   └── common-drift-and-breaks.md
├── android/
│   ├── SKILL.md
│   ├── concepts/sdk-lifecycle.md
│   ├── examples/service-patterns.md
│   ├── references/android-reference-map.md
│   └── troubleshooting/common-issues.md
├── ios/
│   ├── SKILL.md
│   ├── concepts/sdk-lifecycle.md
│   ├── examples/service-patterns.md
│   ├── references/ios-reference-map.md
│   └── troubleshooting/common-issues.md
└── web/
    ├── SKILL.md
    ├── concepts/lifecycle-and-events.md
    ├── examples/app-context-and-state.md
    ├── references/web-reference-map.md
    └── troubleshooting/common-issues.md
```

## Common Lifecycle Pattern

1. Initialize platform context early.
2. Build a channel item (`entryId` for chat/video/ZVA, `apiKey` for scheduled callback and campaign flows).
3. Get service/client instance.
4. Register listeners/delegates before user interaction.
5. Start flow (`fetchUI`, `startVideo`, or web SDK open/show path).
6. Handle engagement state changes (`start`, `hold`, `resume`, `end`) and context switching.
7. End flow and release resources (`endChat`/`endVideo`, `logout/logoff`, uninitialize/release).

## High-Level Scenarios

- Agent side-panel app that stores notes per `engagementId` and survives context switching.
- Browser chat/video campaigns launched from web tags.
- Native mobile customer app for chat/video/scheduled callback.
- Campaign-driven channel selection (chat, ZVA, video, scheduled callback).
- Rejoin flow for dropped video engagements on mobile.
- Smart Embed CRM softphone with postMessage event contracts.

See [scenarios/high-level-scenarios.md](scenarios/high-level-scenarios.md) for details.

## Chaining

- Auth and in-client app identity: [../zoom-apps-sdk/SKILL.md](../zoom-apps-sdk/SKILL.md) and [../oauth/SKILL.md](../oauth/SKILL.md)
- Contact Center REST workflows: [../rest-api/SKILL.md](../rest-api/SKILL.md)
- Cobrowse on web voice/chat channels: [../cobrowse-sdk/SKILL.md](../cobrowse-sdk/SKILL.md)

## Environment Variables

- See [references/environment-variables.md](references/environment-variables.md) for standardized `.env` keys and where to find each value.

# 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

```javascript
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

```javascript
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/`

---
name: contact-center/web
description: "Zoom Contact Center SDK for Web. Use for web chat/video/campaign embeds, engagement event handling, app-context integrations, and Smart Embed postMessage workflows."
user-invocable: false
triggers:
  - "contact center web"
  - "zcc web sdk"
  - "getengagementcontext web"
  - "onengagementcontextchange"
  - "contact center smart embed"
  - "zcc-init-config-request"
---

# Zoom Contact Center SDK - Web

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

## Quick Links

1. [concepts/lifecycle-and-events.md](concepts/lifecycle-and-events.md)
2. [examples/app-context-and-state.md](examples/app-context-and-state.md)
3. [references/web-reference-map.md](references/web-reference-map.md)
4. [troubleshooting/common-issues.md](troubleshooting/common-issues.md)

## Integration Modes

1. Contact Center App in Zoom client:
- Zoom Apps SDK engagement APIs/events.

2. External website embed:
- Campaign SDK/web scripts (`zoomCampaignSdk` pattern).
- Video client initialization pattern.

3. Smart Embed:
- iframe + `postMessage` event contract.

## Hard Guardrails

- For campaign SDK, gate calls behind `zoomCampaignSdk:ready`.
- Persist state by `engagementId`.
- Expect context switching and background app behavior.
- Validate CSP and allow-list settings before debugging logic.

## Chaining

- For in-client app APIs and auth flows: [../../zoom-apps-sdk/SKILL.md](../../zoom-apps-sdk/SKILL.md)
- For identity and OAuth: [../../oauth/SKILL.md](../../oauth/SKILL.md)
- For cobrowse workflow: [../../cobrowse-sdk/SKILL.md](../../cobrowse-sdk/SKILL.md)

## Operations

- [RUNBOOK.md](RUNBOOK.md) - 5-minute preflight and debugging checklist.

# 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.