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 |
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
- Sign in at developer.webex.com and go to My Webex Apps (under your profile)
- Click Create a New App and choose Service App
- Give it a name (e.g., “Serval Integration”), an icon, and a description
- Under Scopes, select:
spark-admin:people_readspark-admin:people_writespark-admin:licenses_readspark-admin:telephony_config_readspark-admin:telephony_config_write
- Click Add Service App and save the generated Client ID and Client Secret
Save the Client Secret securely — you will not be able to access it again after closing the page.
2. Authorize the Service App in Control Hub
- In Control Hub, go to Management → Apps → Service Apps
- Find your new Service App and review the requested scopes
- Toggle Authorize and save
3. Generate the token pair
- Back on developer.webex.com, open your Service App’s page
- In the Org Authorization section, select your organization, enter the Client Secret, and click to generate tokens
- Copy the Refresh Token
4. Connect in Serval
- In Serval, go to Integrations and select Webex
- Enter an organization display name, the Client ID, Client Secret, and Refresh Token
- Click Connect — Serval validates the credentials and refreshes the access token automatically from then on
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.
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) |
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.
