n8n-nodes-genesys-cloud-mcp-plus/README.md

n8n community node for Genesys Cloud MCP Plus - 15 comprehensive tools for contact center analytics, real-time monitoring, and wrap-up code analysis

# n8n-nodes-genesys-cloud-mcp-plus

🚀 **n8n Community Node for Genesys Cloud MCP Plus**

A comprehensive n8n community node providing 15 powerful tools for Genesys Cloud contact center analytics, real-time monitoring, and intelligent conversation analysis.

## 🌟 Features

### 📊 **Historical Analytics (8 Tools)**
- **Search Queues** - Find routing queues by name with wildcard support
- **Query Queue Volumes** - Compare conversation volumes across queues
- **Sample Conversations by Queue** - Get representative conversation samples
- **Voice Call Quality** - Analyze MOS scores and call quality metrics
- **Conversation Sentiment** - Sentiment analysis across interactions
- **Conversation Topics** - Extract business topics and intents
- **Conversation Transcripts** - Full conversation transcripts with timestamps
- **Search Voice Conversations** - Voice-specific conversation search

### ⚡ **Real-Time Monitoring (3 Tools)**
- **Real Time Queue Status** - Live queue metrics and agent availability
- **Real Time Agent Presence** - Current agent status and routing state
- **Live Conversation Monitoring** - Monitor ongoing customer interactions

### 🏷️ **Analytics & Insights (4 Tools)**
- **Wrap Up Code Analytics** - Understand interaction types and volumes
- **Agent Media Type Performance** - Agent performance by media type
- **Agent Status Monitoring** - Agent directory and workforce information
- **Enhanced Conversation Search** - Multi-media conversation search

## 📋 **Supported Media Types**
- 📞 Voice calls
- 💬 Chat interactions  
- 📧 Email conversations
- 📱 SMS/Text messaging
- 🤖 Bot interactions
- 📹 Video calls
- 🌐 Social media interactions
- 📞 Callback requests

## 🛠️ Installation

### NPM Installation
```bash
npm install n8n-nodes-genesys-cloud-mcp-plus
```

### Manual Installation
```bash
git clone https://github.com/amrhero911/n8n-nodes-genesys-cloud-mcp-plus.git
cd n8n-nodes-genesys-cloud-mcp-plus
npm install
npm run build
```

## ⚙️ Configuration

### Credentials Setup
1. Go to your n8n instance
2. Navigate to Settings → Credentials
3. Add new credential: "Genesys Cloud MCP Plus API"
4. Configure with your Genesys Cloud credentials:
   - **Region**: Select your Genesys Cloud region
   - **Client ID**: Your OAuth Client ID
   - **Client Secret**: Your OAuth Client Secret

### Supported Regions
- `mypurecloud.com` (Americas - US East)
- `mypurecloud.de` (EMEA - Europe)
- `mypurecloud.ie` (EMEA - Ireland)
- `mypurecloud.com.au` (APAC - Australia)
- `mypurecloud.jp` (APAC - Japan)
- `cac1.pure.cloud` (Americas - Canada)
- `euw2.pure.cloud` (EMEA - UK West)
- `euc2.pure.cloud` (EMEA - UK Central)
- `aps1.pure.cloud` (APAC - Asia Pacific South)
- `apne2.pure.cloud` (APAC - Asia Pacific Northeast 2)
- `apne3.pure.cloud` (APAC - Asia Pacific Northeast 3)
- `sae1.pure.cloud` (Americas - South America)
- `usw2.pure.cloud` (Americas - US West)
- `mec1.pure.cloud` (EMEA - Middle East)

### OAuth Permissions Required
Your OAuth client needs these permissions:
- `analytics:conversationAggregate:view`
- `analytics:conversationDetail:view`
- `routing:queue:view`
- `users:basic:view`
- `presence:basic:view`
- `speechandtextanalytics:data:view`

## 🚀 Usage

### Node Operations

#### 1. Search Queues
Find routing queues by name with wildcard support.
- **Queue Name**: Queue name or pattern (supports wildcards like *Support*)
- **Page Size**: Number of results per page (max 500)

#### 2. Query Queue Volumes
Compare conversation volumes across queues.
- **Queue IDs**: Comma-separated list of queue IDs (max 300)
- **Start Date**: Start date for the query period
- **End Date**: End date for the query period

#### 3. Sample Conversations by Queue
Get conversation samples from specific queues.
- **Queue ID**: Single queue ID to get conversation samples from
- **Start Date**: Start date for the query period
- **End Date**: End date for the query period

#### 4. Voice Call Quality
Analyze voice call quality metrics (MOS scores).
- **Conversation IDs**: Comma-separated list of conversation IDs (max 100)

#### 5. Conversation Sentiment
Analyze sentiment across conversations.
- **Conversation IDs**: Comma-separated list of conversation IDs (max 100)

#### 6. Conversation Topics
Extract conversation topics and intents.
- **Conversation ID**: Single conversation ID

#### 7. Conversation Transcript
Get full conversation transcripts.
- **Conversation ID**: Single conversation ID

#### 8. Enhanced Conversation Search
Multi-media conversation search across all channels.
- **Start Date**: Start date for the query period
- **End Date**: End date for the query period
- **Phone Number**: Phone number to filter conversations (optional)
- **Media Types**: Media types to filter by (optional)

#### 9. Agent Media Type Performance
Analyze agent performance by media type.
- **Start Date**: Start date for the query period
- **End Date**: End date for the query period
- **Agent IDs**: Comma-separated list of agent IDs (optional)
- **Include Media Breakdown**: Include detailed performance breakdown
- **Page Size**: Number of agents to include in results

#### 10. Real Time Queue Status
Monitor live queue metrics and agent availability.
- **Queue IDs**: Comma-separated list of queue IDs to monitor (max 100)

#### 11. Real Time Agent Presence
Track agent availability and routing status.
- **Agent IDs**: Comma-separated list of agent IDs (optional, max 100)

#### 12. Live Conversation Monitoring
Monitor active customer interactions.
- **Queue IDs**: Comma-separated list of queue IDs to monitor (max 50)
- **Max Results**: Maximum number of conversations to return

#### 13. Wrap Up Code Analytics
Analyze interaction types and volumes by wrap-up codes.
- **Start Date**: Start date for the query period
- **End Date**: End date for the query period
- **Queue IDs**: Comma-separated list of queue IDs to filter by (optional)
- **Wrap Up Codes**: Comma-separated list of specific wrap-up codes (optional)

#### 14. Agent Status Monitoring
Monitor agent directory and workforce information.
- **Agent IDs**: Comma-separated list of agent IDs (optional, max 100)
- **Include Inactive**: Include inactive/disabled agents in results
- **Page Size**: Number of agents to include in results

#### 15. Search Voice Conversations
Search specifically for voice conversations.
- **Start Date**: Start date for the query period
- **End Date**: End date for the query period
- **Phone Number**: Phone number to filter conversations (optional)

## 🔍 Example Workflows

### Business Intelligence Dashboard
1. **Search Queues** → Find relevant queues
2. **Query Queue Volumes** → Get conversation volumes
3. **Wrap Up Code Analytics** → Analyze interaction types
4. **Agent Media Type Performance** → Assess agent efficiency

### Real-Time Operations Monitor
1. **Real Time Queue Status** → Monitor current queue state
2. **Real Time Agent Presence** → Track agent availability
3. **Live Conversation Monitoring** → Monitor active interactions

### Quality Assurance Review
1. **Sample Conversations by Queue** → Get conversation samples
2. **Voice Call Quality** → Check call quality scores
3. **Conversation Sentiment** → Assess customer satisfaction
4. **Conversation Topics** → Extract discussion topics

## 🛡️ Enterprise Features

- **🔒 Secure Authentication** - OAuth 2.0 with client credentials
- **🌍 Multi-Region Support** - Works with all Genesys Cloud regions
- **📊 Comprehensive Analytics** - 15 different analytical perspectives
- **⚡ Real-Time Data** - Live monitoring capabilities
- **🔧 Production Ready** - Error handling, logging, and retry logic

## 📖 Documentation

- [Genesys Cloud API Documentation](https://developer.genesys.cloud/)
- [n8n Community Nodes Guide](https://docs.n8n.io/integrations/community-nodes/)

## 👥 Authors & Contributors

### Original MCP Server Author
**Lucas Woodward** - [MakingChatbots.com](https://makingchatbots.com)
- Created the foundational MCP server with 8 core analytics tools

### n8n Community Node Developer
**Amr Khalil**
- Transformed MCP server into comprehensive n8n community node
- Added 7 additional tools and enhanced existing functionality
- Implemented proper n8n integration and error handling

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## 📝 License

ISC License - see [LICENSE](./LICENSE) for details.

## 🔗 Links

- [GitHub Repository](https://github.com/amrhero911/n8n-nodes-genesys-cloud-mcp-plus)
- [NPM Package](https://www.npmjs.com/package/n8n-nodes-genesys-cloud-mcp-plus)
- [MakingChatbots.com](https://makingchatbots.com)

## 📞 Support

For issues, questions, or feature requests:
- GitHub Issues: [Report here](https://github.com/amrhero911/n8n-nodes-genesys-cloud-mcp-plus/issues)
- Documentation: Check the README for usage details

---

**Built with ❤️ for the n8n and Contact Center Community**