Add wxc-call-intercept playbook (Webex Calling call intercept CLI)

playbooks/wxc-call-intercept/APPHUB.yaml

@@ -0,0 +1,119 @@
+# APPHUB.yaml — Playbook metadata for Webex App Hub
+# Copy this file into your Playbook folder under playbooks/<tool-slug>/
+# Fill in all required fields. See CONTRIBUTING.md for field rules.
+
+# -----------------------------------------------------------------------------
+# friendly_id — Unique identifier. Must end with -playbook (e.g. epic-ehr-playbook)
+# -----------------------------------------------------------------------------
+friendly_id: "wxc-call-intercept-playbook"
+
+# -----------------------------------------------------------------------------
+# title — Display name for the Playbook (matches ContentStack field)
+# -----------------------------------------------------------------------------
+title: "Webex Calling Call Intercept Management"
+
+# -----------------------------------------------------------------------------
+# tag_line — Short tagline for App Hub detail page (required, max 128 chars)
+# -----------------------------------------------------------------------------
+tag_line: "Python sample to read or toggle Webex Calling user call intercept settings with wxc_sdk"
+
+# -----------------------------------------------------------------------------
+# description — App Hub supports Markdown. Use a block scalar (description: |) with
+# blank lines between sections: opening paragraph (bold key terms), **Why use this
+# playbook** (3–5 outcome bullets), **What it does** (concrete behaviors/endpoints).
+# Do not put upstream repo URLs or install-only instructions here—use README and
+# src/README.md for reference playbooks. See docs/commands/import_playbook.md.
+# -----------------------------------------------------------------------------
+description: |
+  A **Python** CLI that uses **wxc_sdk** and documented **Webex Calling** APIs to **read**
+  and **toggle** **call intercept** (on/off) for a user identified by **email**.
+
+  **Why use this playbook**
+
+  - **Ship faster:** Start from a working **People** lookup plus **person_settings.call_intercept**
+    flow instead of reverse-engineering payloads from scratch.
+  - **Flexible auth:** Supports a passed-in token, **WEBEX_ACCESS_TOKEN**, or **OAuth** via
+    integration credentials loaded from the environment.
+  - **Secrets-safe pattern:** Integration IDs, secrets, and tokens are intended for
+    **environment variables** (see **env.template**), not hardcoded values.
+  - **Easy to verify:** Single-user CLI with optional **debug** logging for REST traces during
+    development.
+
+  **What it does**
+
+  - Resolves **person_id** by listing **People** with the target **email**.
+  - Calls **person_settings.call_intercept.read** to print whether intercept is **on** or **off**.
+  - Optionally calls **person_settings.call_intercept.configure** when you pass **on** or **off**,
+    then re-reads to confirm the new state.
+  - Can obtain tokens through a local **OAuth** redirect to **localhost:6001** and cache them in
+    a YAML file next to the script.
+
+# -----------------------------------------------------------------------------
+# product_types — Where this Playbook appears. Pick one or more.
+# Valid: teams | meetings | calling | rooms | contact_center
+# -----------------------------------------------------------------------------
+product_types:
+  - "calling"
+
+# -----------------------------------------------------------------------------
+# categories — App Hub category slugs. Pick one or more.
+# Verticals: healthcare | financial-services | retail-ecommerce
+# App categories (use kebab-case slugs):
+#   ai-agent-testing-observability | agent-supervisor-tools | analytics |
+#   calendar-scheduling | collaboration-management | customer-relations |
+#   customer-support | developer-tools | doc-management | education |
+#   finance | government | healthcare | human-resources | internet-of-things |
+#   marketing-sales | orchestration | platform | productivity |
+#   project-management | recording-transcriptions | security-compliance |
+#   self-service-bots | social-and-fun | strategy-team-planning |
+#   workflow-automation | workforce-optimization | other
+# -----------------------------------------------------------------------------
+categories:
+  - "developer-tools"
+  - "productivity"
+
+# -----------------------------------------------------------------------------
+# company_name — Your company or team name
+# -----------------------------------------------------------------------------
+company_name: "Webex for Developers"
+
+# -----------------------------------------------------------------------------
+# company_url — Your company or project URL
+# -----------------------------------------------------------------------------
+company_url: "https://developer.webex.com"
+
+# -----------------------------------------------------------------------------
+# support_url — Issues or support link (e.g. GitHub issues)
+# -----------------------------------------------------------------------------
+support_url: "https://github.com/webex/webexplaybooks/issues"
+
+# -----------------------------------------------------------------------------
+# product_url — Link to this Playbook in the repo (required)
+# -----------------------------------------------------------------------------
+product_url: "https://github.com/webex/webexplaybooks/tree/main/playbooks/wxc-call-intercept"
+
+# -----------------------------------------------------------------------------
+# logo — (Optional) URL to your logo image. If not provided, defaults to the
+# standard Webex Playbook logo.
+# -----------------------------------------------------------------------------
+logo: "https://images.contentstack.io/v3/assets/bltd14fd2a03236233f/blta2de9daa773c6604/60f71f81e2de935fc7e35dbe/download"
+
+# -----------------------------------------------------------------------------
+# estimated_implementation_time — e.g. "2-4 hours", "1 day"
+# -----------------------------------------------------------------------------
+estimated_implementation_time: "1-2 hours"
+
+# -----------------------------------------------------------------------------
+# third_party_tool — (Optional) The tool being integrated (e.g. Salesforce, Epic)
+# Omit for generic playbooks (e.g. "any CMS")
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# privacy_url — Privacy policy URL (required; use Cisco default for Webex-authored)
+# -----------------------------------------------------------------------------
+privacy_url: "https://www.cisco.com/c/en/us/about/legal/privacy-full.html"
+
+# -----------------------------------------------------------------------------
+# submission_date — (Optional) ISO date (e.g. 2025-03-01)
+# -----------------------------------------------------------------------------
+submission_date: "2026-04-02"

playbooks/wxc-call-intercept/README.md

@@ -0,0 +1,56 @@
+# Webex Calling Call Intercept Management
+
+This Playbook is adapted from the [wxc_call_intercept](https://github.com/jeokrohn/wxc_call_intercept) sample on GitHub.
+
+## Use Case Overview
+
+Administrators and developers need a quick, scriptable way to **read** whether **call intercept** is enabled for a **Webex Calling** user and to **turn it on or off** without opening Control Hub for every change. This Playbook provides a minimal **Python** CLI that uses the **wxc_sdk** against documented **Webex** person-settings APIs. It is aimed at **IT admins**, **integration developers**, and **partners** automating user telephony settings. **Estimated implementation time:** 1–2 hours (integration app or token setup, Python environment, first successful run).
+
+## Architecture
+
+The sample runs **locally** as a command-line script. It authenticates with a **Webex access token** (CLI argument, `WEBEX_ACCESS_TOKEN`, or **OAuth** via integration credentials and a localhost redirect), resolves the target user by **email** with the **People** API, then calls **person settings → call intercept** to **read** the current state and optionally **configure** intercept on or off. Authentication and REST traffic go to **Webex** cloud endpoints; no separate third-party service is involved. For a sequence view of token acquisition, user lookup, and intercept read/update, see [diagrams/architecture-diagram.md](diagrams/architecture-diagram.md).
+
+## Prerequisites
+
+- **Webex organization** with **Webex Calling** licensed for the target users.
+- **API access** sufficient to:
+  - List people by email and read `personId` (People API).
+  - Read and update **call intercept** person settings for those users (scopes must match your chosen auth path—typically an **admin** or **integration** with the appropriate **spark** scopes; align with your integration or token documentation).
+- One of the following **authentication** approaches:
+  - A valid **access token** passed as `--token` or in `WEBEX_ACCESS_TOKEN`, **or**
+  - A **Webex Integration** with **Client ID**, **Client Secret**, and **scopes** configured; the sample uses OAuth with redirect `http://localhost:6001/redirect` and persists tokens to a local YAML file next to the script.
+- **Developer environment:** **Python 3** (3.8+ recommended) and **pip**.
+- **Network:** Outbound **HTTPS** to Webex API hosts; for OAuth, local browser access to **localhost:6001** during token acquisition.
+- **Compliance:** Only run against users and orgs you are authorized to administer.
+
+## Code Scaffold
+
+Under **`src/`**:
+
+| File | Purpose |
+|------|---------|
+| `call_intercept.py` | CLI: `user_email` plus optional `on`/`off`; reads intercept state; updates if `on` or `off` is supplied. |
+| `env.template` | Copy to `.env` (or export variables) for **OAuth** integration parameters. |
+| `requirements.txt` | Pinned Python dependencies (including **wxc-sdk**) for a reproducible install. |
+
+The script demonstrates **WebexSimpleApi**, **People** listing, and **person_settings.call_intercept** **read**/**configure**. It does **not** provide production logging, retries, bulk operations, secure token storage, or Control Hub UI parity. **Secrets** belong in **environment variables** or your secret manager—not in source control.
+
+## Deployment Guide
+
+1. **Clone this repository** (or copy `playbooks/wxc-call-intercept/src/`) to your machine.
+2. **Create a Python virtual environment** (recommended): `python3 -m venv .venv && source .venv/bin/activate` (on Windows, `.venv\Scripts\activate`).
+3. **Install dependencies:** from `playbooks/wxc-call-intercept/src/`, run `pip install -r requirements.txt`.
+4. **Choose authentication:**
+   - **Option A — Existing token:** Obtain an access token with scopes that allow people lookup and call intercept person settings. Export `WEBEX_ACCESS_TOKEN` or pass `--token <token>`.
+   - **Option B — Integration OAuth:** In [Webex for Developers](https://developer.webex.com), create an **Integration** with redirect URI **`http://localhost:6001/redirect`**. Copy **`src/env.template`** to **`.env`** in your working directory (or set exports) and fill `TOKEN_INTEGRATION_CLIENT_ID`, `TOKEN_INTEGRATION_CLIENT_SECRET`, and `TOKEN_INTEGRATION_CLIENT_SCOPES`.
+5. **Run from the directory containing your `.env`** (if using OAuth): `python call_intercept.py <user@example.com>` to print `on` or `off`.
+6. **Update intercept:** `python call_intercept.py <user@example.com> on` or `... off` to set intercept and print confirmation.
+7. **Debug REST traffic (optional):** add `-d` / `--debug` for verbose logging.
+
+## Known Limitations
+
+- **Rate limits** and throttling apply per **Webex** API policy; the sample does not implement backoff or batching.
+- **Access tokens expire**; refresh or re-run OAuth as appropriate. Token cache is a **local YAML** file—**not** suitable for shared or production systems without hardening.
+- The upstream sample repository did not include a **`LICENSE`** file in the checked-out tree; confirm license terms on the [source repository](https://github.com/jeokrohn/wxc_call_intercept) before redistribution. This Playbook’s use is also subject to the playbook repository [LICENSE](../../LICENSE).
+- **SDK and API versions** may change; validate behavior after upgrading **wxc-sdk**.
+- This Playbook is provided as a starting point. Webex does not guarantee the functional accuracy of the source code. Test thoroughly before use in a production environment.

playbooks/wxc-call-intercept/diagrams/architecture-diagram.md

@@ -0,0 +1,34 @@
+# Architecture — Webex Calling call intercept CLI
+
+This diagram shows how the sample CLI authenticates, resolves a user, and reads or updates **call intercept** via **Webex** APIs.
+
+```mermaid
+sequenceDiagram
+    participant Admin as AdminOrDeveloper
+    participant CLI as call_intercept.py
+    participant Token as TokenSource
+    participant Webex as WebexAPIS
+
+    Admin->>CLI: Run with user email optional on/off
+    alt CLI token or WEBEX_ACCESS_TOKEN
+        CLI->>Token: Use provided access token string
+    else OAuth integration env vars
+        CLI->>Token: build_integration TOKEN_INTEGRATION_*
+        Token->>Webex: OAuth authorize redirect localhost:6001
+        Admin->>Token: Browser completes login consent
+        Token-->>CLI: Access token cached in local YAML
+    end
+    CLI->>Webex: People list filter by email
+    Webex-->>CLI: person_id
+    CLI->>Webex: person_settings.call_intercept.read
+    Webex-->>CLI: intercept enabled state
+    alt Optional on or off argument
+        CLI->>Webex: person_settings.call_intercept.configure
+        Webex-->>CLI: Success
+        CLI->>Webex: person_settings.call_intercept.read
+        Webex-->>CLI: Updated state
+    end
+    CLI-->>Admin: Print on or off set to on/off
+```
+
+Note: Sequence labels use simplified endpoint names; the **wxc_sdk** maps these to documented REST resources.