> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webex

## About Webex

Webex is Cisco's collaboration and calling platform. Connecting Webex to Serval enables automated user provisioning and voice management: creating, updating, and removing Webex users, and assigning Webex Calling phone numbers to their profiles directly from your service desk.

## What the Webex integration enables

| Capability              | Description                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| User Management         | Create, look up, update, and remove Webex user accounts                                                |
| Calling Enablement      | Assign Webex Calling licenses and locations to users                                                   |
| Phone Number Management | Assign and unassign phone numbers and extensions, list available numbers, and add numbers to locations |
| Automation workflows    | Automate joiner/mover/leaver flows for your voice platform                                             |

Anything defined in the [Webex People API](https://developer.webex.com/admin/docs/api/v1/people) and [Webex Calling configuration APIs](https://developer.webex.com/docs/api/v1/numbers) can be accessed through Serval.

***

## Webex Configuration

Serval connects to Webex with a **Service App** — a machine account that a full administrator authorizes once for your organization. Unlike a personal OAuth integration, a Service App keeps working even if the authorizing administrator leaves or changes their password.

### Prerequisites

* You must be a **Full Administrator** of your Webex organization
* Your organization must have Webex Calling licenses for voice features

### 1. Create a Service App

1. Sign in at [developer.webex.com](https://developer.webex.com) and go to **My Webex Apps** (under your profile)
2. Click **Create a New App** and choose **Service App**
3. Give it a name (e.g., "Serval Integration"), an icon, and a description
4. Under **Scopes**, select:
   * `spark-admin:people_read`
   * `spark-admin:people_write`
   * `spark-admin:licenses_read`
   * `spark-admin:telephony_config_read`
   * `spark-admin:telephony_config_write`
5. Click **Add Service App** and save the generated **Client ID** and **Client Secret**

<Warning>
  Save the Client Secret securely — you will not be able to access it again after closing the page.
</Warning>

### 2. Authorize the Service App in Control Hub

1. In [Control Hub](https://admin.webex.com), go to **Management → Apps → Service Apps**
2. Find your new Service App and review the requested scopes
3. Toggle **Authorize** and save

### 3. Generate the token pair

1. Back on [developer.webex.com](https://developer.webex.com), open your Service App's page
2. In the **Org Authorization** section, select your organization, enter the Client Secret, and click to generate tokens
3. Copy the **Refresh Token**

### 4. Connect in Serval

1. In Serval, go to **Integrations** and select **Webex**
2. Enter an organization display name, the **Client ID**, **Client Secret**, and **Refresh Token**
3. Click **Connect** — Serval validates the credentials and refreshes the access token automatically from then on

<Note>
  Webex access tokens last about 14 days and refresh tokens about 90 days; every automatic refresh renews both, so the connection stays healthy indefinitely while in regular use.
</Note>

***

## Included workflows

### User management

| Workflow          | Description                                           |
| ----------------- | ----------------------------------------------------- |
| Create Webex User | Create a new user account (sends an activation email) |
| Get Webex User    | Look up a user by email, including calling details    |
| Update Webex User | Update name, display name, department, or title       |
| Delete Webex User | Remove a user from the organization                   |

### Voice & phone number management

| Workflow                              | Description                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| Enable Webex Calling for User         | Assign a calling license, location, and primary number/extension in one step |
| Assign Phone Number to Webex User     | Add a number (and optional extension) to a calling-enabled user              |
| Unassign Phone Number from Webex User | Return an alternate number to the location's pool                            |
| Get Webex User Phone Numbers          | List the numbers assigned to a user                                          |
| List Webex Phone Numbers              | List org numbers, filterable to available numbers or a location              |
| Add Phone Numbers to Webex Location   | Add PSTN numbers to a location (non-integrated PSTN only)                    |

<Note>
  Phone numbers in Webex belong to **locations**. A user must have a Webex Calling license and a location before a number can be assigned, and the number must already exist (unassigned) in that location. The "Enable Webex Calling for User" workflow handles all three steps together.
</Note>