{"id":29617133,"url":"https://github.com/webexsamples/webex-contact-center-agent-desktop-api-sample","last_synced_at":"2026-07-03T01:01:52.266Z","repository":{"id":305225595,"uuid":"885068193","full_name":"WebexSamples/webex-contact-center-agent-desktop-api-sample","owner":"WebexSamples","description":"Webex CC RESTful API Agent Desktop STARTER","archived":false,"fork":false,"pushed_at":"2025-07-18T20:20:32.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-28T01:40:31.443Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebexSamples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-07T22:32:38.000Z","updated_at":"2025-07-18T20:20:35.000Z","dependencies_parsed_at":"2025-07-19T01:32:51.467Z","dependency_job_id":null,"html_url":"https://github.com/WebexSamples/webex-contact-center-agent-desktop-api-sample","commit_stats":null,"previous_names":["webexsamples/webex-contact-center-agent-desktop-api-sample"],"tags_count":0,"template":false,"template_full_name":"WebexSamples/Webex-Samples-Template","purl":"pkg:github/WebexSamples/webex-contact-center-agent-desktop-api-sample","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebexSamples%2Fwebex-contact-center-agent-desktop-api-sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebexSamples%2Fwebex-contact-center-agent-desktop-api-sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebexSamples%2Fwebex-contact-center-agent-desktop-api-sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebexSamples%2Fwebex-contact-center-agent-desktop-api-sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebexSamples","download_url":"https://codeload.github.com/WebexSamples/webex-contact-center-agent-desktop-api-sample/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebexSamples%2Fwebex-contact-center-agent-desktop-api-sample/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35068135,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-21T01:33:39.081Z","updated_at":"2026-07-03T01:01:50.211Z","avatar_url":"https://github.com/WebexSamples.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Webex Contact Center Agent Desktop API Sample\n\nA comprehensive Flask application demonstrating how to integrate with the Webex Contact Center REST API. This sample showcases agent desktop session management, OAuth authentication, and seamless integration with Webex Contact Center services.\n\n## 🎯 Features\n\nThis sample shows how to use the Webex Contact Center API to do the following:\n\n* **OAuth Authentication** with Webex Contact Center\n* **Agent Login** to desktop sessions programmatically  \n* **Agent Logout** from desktop sessions\n* **Token Management** with automatic refresh handling\n* **Session Management** with Flask session storage\n* **Error Handling** with retry logic for expired tokens\n\n## 📚 Prerequisites\n\n### Software Requirements\n\n- **Python 3.6 or higher**\n- **Flask** web framework\n- **Requests** library for HTTP calls\n\n### Webex Contact Center Requirements\n\n- **Webex Contact Center Account** or [Developer Sandbox](https://developer.webex-cx.com/sandbox)\n- **Webex Contact Center Integration** with `cjp:user` scope\n- **Agent ID** and **Team ID** from your Contact Center configuration\n- **Dial Number** for agent extension\n\n## 🚀 Quick Start\n\n### Getting Your Integration Credentials\n\n1. **Request Developer Sandbox**: Visit [developer.webex-cx.com/sandbox](https://developer.webex-cx.com/sandbox)\n2. **Register Integration**: Create a Webex Contact Center integration with `cjp:user` scope\n3. **Learn More**: [Integration Documentation](https://developer.webex-cx.com/documentation/integrations)\n4. **Gather Required Information**:\n   - Client ID and Client Secret\n   - Agent ID (from Control Hub or WebSocket notifications)\n   - Team ID (from Control Hub or WebSocket notifications)\n   - Dial Number for agent\n\n### Setup Instructions\n\n1. **Clone the repository:**\n\n   ```sh\n   git clone https://github.com/your-repo/webex-contact-center-integration.git\n   cd webex-contact-center-integration\n   ```\n\n2. **Install dependencies:**\n\n   ```sh\n   pip install -r requirements.txt\n   ```\n\n   Or install manually:\n\n   ```sh\n   pip install flask requests\n   ```\n\n3. **Configure variables in `desktop.py`:**\n\n   ```python\n   CLIENT_ID = \"YourClientId\"\n   CLIENT_SECRET = \"YourClientSecret\"\n   REDIRECT_URI = \"http://0.0.0.0:10060/oauth\"\n   AGENT_ID = \"YourAgentId\"\n   TEAM_ID = \"YourTeamId\"\n   DIAL_NUMBER = \"1001\"\n   ```\n\n4. **Add Authorization URL in `templates/index.html`:**\n\n   ```html\n   \u003ca href='Your Authorization URL here'\u003e\n   ```\n\n5. **Start the application:**\n\n   ```sh\n   python3 desktop.py\n   ```\n\n6. **Access the application:**\n\n   Open your browser and navigate to `http://127.0.0.1:10060`\n\n## 📁 Project Structure\n\n```\nwebex-contact-center-agent-desktop-api-sample/\n├── desktop.py              # Main Flask application\n├── requirements.txt        # Python dependencies\n├── static/css/            # CSS styling files\n├── templates/             # HTML templates\n│   ├── index.html         # Main authorization page\n│   ├── granted.html       # Post-authorization page\n│   ├── agent_loggedin.html # Agent logged in state\n│   └── temp.html          # Base template\n├── package.json           # Development tools configuration\n└── README.md              # This file\n```\n\n## 🔧 Functionality Overview\n\n### Core Features\n\n| Feature | Description | API Endpoint |\n|---------|-------------|--------------|\n| **OAuth Flow** | Authenticate with Webex Contact Center | `/v1/access_token` |\n| **Agent Login** | Start agent desktop session | `/v1/agents/login` |\n| **Agent Logout** | End agent desktop session | `/v1/agents/logout` |\n| **Token Refresh** | Automatically refresh expired tokens | `/v1/access_token` |\n\n### Application Flow\n\n1. **Authorization**: Agent clicks \"Connect to WxCC\" to start OAuth flow\n2. **Token Exchange**: Authorization code exchanged for access and refresh tokens\n3. **Agent Login**: Agent clicks \"Agent Login\" to start desktop session\n4. **Session Active**: Agent can handle calls and perform contact center functions\n5. **Agent Logout**: Agent clicks \"Agent Logout\" to end desktop session\n\n## 🔐 Authentication \u0026 Authorization\n\n### OAuth 2.0 Flow\n\nThe application implements the standard OAuth 2.0 authorization code flow:\n\n```python\n# Token exchange\ndef get_tokens(code):\n    url = \"https://webexapis.com/v1/access_token\"\n    payload = {\n        \"grant_type\": \"authorization_code\",\n        \"client_id\": CLIENT_ID,\n        \"client_secret\": CLIENT_SECRET,\n        \"code\": code,\n        \"redirect_uri\": REDIRECT_URI\n    }\n    # Exchange code for tokens\n```\n\n### Token Management\n\nThe application includes automatic token refresh:\n\n```python\ndef get_tokens_refresh():\n    # Refresh expired access tokens using refresh token\n    payload = {\n        \"grant_type\": \"refresh_token\",\n        \"client_id\": CLIENT_ID,\n        \"client_secret\": CLIENT_SECRET,\n        \"refresh_token\": session['refresh_token']\n    }\n```\n\n## 📡 API Integration\n\n### Agent Login\n\n```python\n@app.route(\"/agentlogin\", methods=['POST'])\ndef agentLogin():\n    url = \"https://api.wxcc-us1.cisco.com/v1/agents/login\"\n    payload = {\n        \"dialNumber\": dialNumber,\n        \"teamId\": teamId,\n        \"isExtension\": True,\n        \"roles\": [\"agent\"],\n        \"deviceType\": \"BROWSER\"\n    }\n    headers = {\n        \"Content-Type\": \"application/json\",\n        \"Authorization\": f\"Bearer {access_token}\"\n    }\n```\n\n### Agent Logout\n\n```python\n@app.route(\"/agentlogout\", methods=['POST'])\ndef agentLogout():\n    url = \"https://api.wxcc-us1.cisco.com/v1/agents/logout\"\n    payload = {\n        \"logoutReason\": \"AGENT_LOGOUT from sample app\",\n        \"agentId\": agentId\n    }\n```\n\n### Error Handling\n\nThe application includes comprehensive error handling with automatic retry:\n\n```python\nif response.status_code != 202:\n    if response.status_code == 401:\n        get_tokens_refresh()  # Refresh token and retry\n        response = requests.request(\"POST\", url, json=payload, headers=headers)\n```\n\n## 🎨 User Interface\n\nThe application uses a clean, minimal web interface with:\n\n- **Bootstrap-style CSS** for professional appearance\n- **Flask templates** with inheritance for maintainable code\n- **Form-based interactions** for agent login/logout\n- **Responsive design** that works on desktop and mobile\n\n### Page Flow\n\n1. **index.html**: Main page with \"Connect to WxCC\" button\n2. **granted.html**: Post-authorization page with \"Agent Login\" button\n3. **agent_loggedin.html**: Active session page with \"Agent Logout\" button\n\n## 🔧 Configuration Details\n\n### Required Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `CLIENT_ID` | Integration Client ID | `C1234567890abcdef...` |\n| `CLIENT_SECRET` | Integration Client Secret | `secret123...` |\n| `REDIRECT_URI` | OAuth redirect URL | `http://0.0.0.0:10060/oauth` |\n| `AGENT_ID` | Contact Center Agent ID | `agent123@example.com` |\n| `TEAM_ID` | Contact Center Team ID | `team456` |\n| `DIAL_NUMBER` | Agent extension number | `1001` |\n\n### Finding Agent and Team IDs\n\nYou can obtain Agent ID and Team ID through:\n\n1. **Control Hub**: Webex Contact Center administration portal\n2. **WebSocket Notifications**: [Subscribe to notifications](https://developer.webex-cx.com/documentation/notification/v1/subscribe-notification)\n3. **API Calls**: Use Contact Center APIs to retrieve user and team information\n\n## 🌐 Production Considerations\n\n### Security Best Practices\n\n1. **Environment Variables**: Store credentials in environment variables, not source code\n2. **HTTPS**: Use HTTPS in production for secure token transmission\n3. **Token Storage**: Implement secure token storage (not Flask sessions)\n4. **Rate Limiting**: Implement API rate limiting and retry logic\n\n### Deployment\n\nFor production deployment:\n\n```python\n# Use environment variables\nimport os\nCLIENT_ID = os.getenv('WXCC_CLIENT_ID')\nCLIENT_SECRET = os.getenv('WXCC_CLIENT_SECRET')\nAGENT_ID = os.getenv('WXCC_AGENT_ID')\n```\n\n### Error Handling\n\n```python\n# Enhanced error handling for production\ntry:\n    response = requests.post(url, json=payload, headers=headers, timeout=30)\n    response.raise_for_status()\nexcept requests.exceptions.RequestException as e:\n    logger.error(f\"API call failed: {e}\")\n    # Implement retry logic or user notification\n```\n\n## 🔧 Development\n\n### Local Development\n\n1. **Virtual Environment**:\n   ```sh\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   pip install -r requirements.txt\n   ```\n\n2. **Debug Mode**:\n   ```python\n   if __name__ == '__main__':\n       app.run(\"0.0.0.0\", port=10060, debug=True)\n   ```\n\n### Adding Features\n\nExample: Adding agent state management:\n\n```python\n@app.route(\"/agentstatus\", methods=['GET'])\ndef agentStatus():\n    url = \"https://api.wxcc-us1.cisco.com/v1/agents/status\"\n    headers = {\"Authorization\": f\"Bearer {session['oauth_token']}\"}\n    response = requests.get(url, headers=headers)\n    return response.json()\n```\n\n## 🔗 Related Resources\n\n- [Webex Contact Center Developer Portal](https://developer.webex-cx.com/)\n- [Contact Center API Documentation](https://developer.webex-cx.com/documentation/rest-api)\n- [Integration Management](https://developer.webex-cx.com/documentation/integrations)\n- [Developer Sandbox Request](https://developer.webex-cx.com/sandbox)\n- [WebSocket Notifications](https://developer.webex-cx.com/documentation/notification)\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly with Contact Center environment\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the **Cisco Sample Code License**.\n\n### License Summary\n\n- ✅ **Permitted**: Copy, modify, and redistribute for use with Cisco products\n- ❌ **Prohibited**: Use independent of Cisco products or to compete with Cisco\n- ℹ️ **Warranty**: Provided \"as is\" without warranty\n- ℹ️ **Support**: Not supported by Cisco TAC\n\nSee the [LICENSE](LICENSE) file for full license terms.\n\n## 🆘 Support\n\n- Create an issue in this repository\n- Visit [Webex Contact Center Developer Support](https://developer.webex-cx.com/support)\n- Join the [Webex Developer Community](https://developer.webex.com/community)\n\n---\n\n**Ready to integrate with Webex Contact Center!** 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebexsamples%2Fwebex-contact-center-agent-desktop-api-sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebexsamples%2Fwebex-contact-center-agent-desktop-api-sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebexsamples%2Fwebex-contact-center-agent-desktop-api-sample/lists"}