n8n-nodes-napcat

A comprehensive n8n community node for NapCat QQ Bot API integration. This node allows you to seamlessly integrate QQ bot functionality into your n8n workflows, enabling automated messaging, account management, and group operations.

🚀 Features

📱 Message Operations (8 operations)

• Send Private Messages: Send text, images, voice, video and other media to private chats
• Send Group Messages: Send text, images, voice, video and other media to group chats
• Recall Messages: Recall sent messages
• Get Group History: Retrieve group chat message history
• Get Friend History: Retrieve private chat message history
• Get Message Details: Get detailed information about specific messages
• Send Poke: Send poke messages
• Stick Expression: Stick expressions on messages

👤 Account Operations (15 operations)

• Get Account Info: Get current logged-in account information
• Get Friend List: Get all friends list
• Get One-way Friends: Get one-way friends list
• Get Friend Groups: Get friend groups list
• Set Friend Remark: Set friend's remark name
• Delete Friend: Delete specified friend
• Handle Friend Request: Handle friend add requests
• Set Signature: Set personal signature
• Set Avatar: Set personal avatar
• Set Online Status: Set online status
• Get User Status: Get specified user's online status
• Like: Like specified user
• Get Like List: Get like list
• Create Collection: Create collection content
• Get Collection List: Get collection list

🏢 Group Operations (18 operations)

• Get Group List: Get all groups the account has joined
• Get Group Info: Get detailed group information
• Get Group Members: Get group member list
• Get Group Member Info: Get detailed group member information
• Set Group Name: Modify group name
• Set Group Avatar: Set group avatar
• Set Group Remark: Set group remark
• Kick Group Member: Kick specified member from group
• Batch Kick Members: Kick multiple group members
• Mute Group Member: Mute specified group member
• Mute All: Set group-wide mute
• Set Group Admin: Set or remove group admin
• Set Member Card: Set group member's card in group
• Set Group Title: Set group member's title
• Leave Group: Leave specified group
• Handle Group Request: Handle group join requests
• Get Group Essence: Get group essence messages list
• Set Group Essence: Set group essence message
• Get Group Honor: Get group honor information

📁 File Operations (9 operations)

• Upload Group File: Upload files to group chat
• Upload Private File: Upload files to private chat
• Get Group Files: Get group file list
• Get File Info: Get detailed file information
• Download File: Download files to local
• Get File Link: Get file download link
• Delete Group File: Delete group files
• Move Group File: Move group files to other folders
• Rename Group File: Rename group files

🔑 Key Operations (5 operations)

• Get ClientKey: Get ClientKey
• Get Cookies: Get Cookies information
• Get CSRF Token: Get CSRF Token
• Get QQ Credentials: Get QQ related interface credentials
• Get RKey: Get RKey

🎯 Personal Operations (6 operations)

• OCR Image Recognition: Use OCR to recognize text in images
• English to Chinese: Translate English to Chinese
• Get AI Voice: Get AI voice
• Get AI Voice Characters: Get available AI voice characters list
• Set Input Status: Set input status
• Click Button: Click interface buttons

⚙️ System Operations (5 operations)

• Get Version Info: Get NapCat version information
• Get Bot Account Range: Get bot account range
• Account Logout: Logout current account
• Send Custom Packet: Send custom data packets
• Get Packet Status: Get packet status

📦 Installation

Method 1: Community Node Installation (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Click Install a community node
4. Enter package name: n8n-nodes-napcat
5. Click Install and wait for installation to complete

Method 2: Manual Installation

1. Clone this repository:

   git clone https://github.com/your-username/n8n-nodes-napcat.git
   cd n8n-nodes-napcat
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Copy the dist folder to your n8n community nodes directory:

   # For Docker installations
   docker cp dist/. your-n8n-container:/home/node/.n8n/community-packages/n8n-nodes-napcat/
   
   # For local installations
   cp -r dist ~/.n8n/community-packages/n8n-nodes-napcat/
   

5. Restart n8n

🔧 Configuration

Prerequisites

Before using this node, ensure you have:

1. NapCat Service Running: Your NapCat QQ bot service must be running and accessible
2. API Access: Ensure your NapCat API is properly configured and accessible
3. Valid Credentials: Have your NapCat API credentials ready

Setting Up Credentials

1. In your n8n workflow, add a NapCat node

2. Click on the Credentials field

3. Create new credentials with the following information:

   Field	Description	Example	Required
   API Base URL	The base URL of your NapCat API server	http://napcat:3000 or http://localhost:3000	✅
   Access Token	NapCat API access token (Bearer Token)	your-bearer-token	✅

Authentication Configuration

NapCat API uses Bearer Token authentication:

1. Get Token: Obtain access token from your NapCat service
2. Configure URL:
   • Local deployment: http://localhost:3000
   • Docker deployment: http://napcat:3000
   • Remote server: http://your-server:3000
3. Test Connection: The node will automatically test API connection

Common Issues

Q: Authentication failed?
A: Please check:

• NapCat service is running properly
• API Base URL is correct
• Access Token is valid
• Network connection is working

Q: How to get Access Token?
A: Please refer to NapCat API Documentation for detailed authentication instructions

🚀 Quick Start

1. Install Node

npm install n8n-nodes-napcat

2. Configure Authentication

1. Add NapCat node in n8n
2. Create new credentials:
   • API Base URL: http://napcat:3000 (or http://localhost:3000)
   • Access Token: Your Bearer Token

3. Send Message

1. Select Resource: Message Operations
2. Select Operation: Send Private Message
3. Configure parameters:
   • User ID: Target user QQ number
   • Message Type: Text
   • Message Content: Message content to send
4. Execute workflow

4. Get Account Info

1. Select Resource: Account Operations
2. Select Operation: Get Account Info
3. Execute workflow

Node Parameters

Message Operations

Parameter	Type	Required	Description
Resource	Options	Yes	Choose between "Message" or "Account"
Operation	Options	Yes	Select the specific operation to perform
User ID	String	For private messages	Target user's QQ number
Group ID	String	For group messages	Target group's QQ number
Message Type	Options	Yes	Choose "Text" or "Image"
Message Content	String	For text messages	The text content to send
Image URL	String	For image messages	URL or base64 data of the image

Account Operations

Parameter	Type	Required	Description
Resource	Options	Yes	Set to "Account"
Operation	Options	Yes	Choose "Get Account Info"

📖 Usage Examples

Example 1: Send a Private Message

1. Add NapCat Node: Drag the NapCat node to your workflow
2. Configure Node:
   • Resource: Message
   • Operation: Send Private Message
   • User ID: 123456789 (target user's QQ number)
   • Message Type: Text
   • Message Content: Hello from n8n!
3. Execute: Run the workflow to send the message

Example 2: Send a Group Message

1. Add NapCat Node: Drag the NapCat node to your workflow
2. Configure Node:
   • Resource: Message
   • Operation: Send Group Message
   • Group ID: 987654321 (target group's QQ number)
   • Message Type: Text
   • Message Content: Automated message from n8n workflow
3. Execute: Run the workflow to send the group message

Example 3: Get Account Information

1. Add NapCat Node: Drag the NapCat node to your workflow
2. Configure Node:
   • Resource: Account
   • Operation: Get Account Info
3. Execute: Run the workflow to retrieve account information

Example 4: Advanced Workflow - Automated Response

{
  "nodes": [
    {
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook"
    },
    {
      "name": "Process Data",
      "type": "n8n-nodes-base.function",
      "parameters": {
        "functionCode": "// Process incoming data\nreturn { userId: $json.userId, message: $json.message };"
      }
    },
    {
      "name": "Send QQ Message",
      "type": "n8n-nodes-napcat.napCat",
      "parameters": {
        "resource": "message",
        "operation": "sendPrivateMessage",
        "userId": "={{ $json.userId }}",
        "messageType": "text",
        "messageContent": "={{ $json.message }}"
      }
    }
  ]
}

🔌 API Reference

This node integrates with the NapCat API and supports the following endpoints:

Message Endpoints

• POST /send_private_msg - Send private messages
• POST /send_group_msg - Send group messages
• POST /get_friend_history_msg - Get private message history
• POST /get_group_history_msg - Get group message history
• POST /delete_msg - Recall messages

Account Endpoints

• POST /get_login_info - Get account information
• POST /get_friend_list - Get friend list
• POST /get_group_list - Get group list

Group Endpoints

• POST /get_group_info - Get group information
• POST /get_group_member_list - Get group members
• POST /set_group_name - Set group name

🛠️ Development

Prerequisites

• Node.js 18 or higher
• TypeScript 5.0 or higher
• n8n (for testing)

Getting Started

1. Clone the repository:

   git clone https://github.com/your-username/n8n-nodes-napcat.git
   cd n8n-nodes-napcat
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Run tests:

   node test-node.js
   

Development Scripts

Script	Description
npm run build	Build the TypeScript project
npm run dev	Start development mode with watch
npm run lint	Run ESLint for code quality
npm run format	Format code with Prettier
npm test	Run the test suite

Project Structure

n8n-nodes-napcat/
├── dist/                          # Built output
├── credentials/                   # Credential definitions
├── nodes/                        # Node implementations
├── examples/                     # Example workflows
├── src/                          # Source TypeScript files
├── package.json                  # Project configuration
├── tsconfig.json                 # TypeScript configuration
└── README.md                     # This file

🐛 Troubleshooting

Common Issues

1. Node Not Appearing in n8n

Problem: NapCat node doesn't appear in the node palette
Solution:

• Ensure the node is properly installed
• Restart n8n after installation
• Check n8n logs for any errors

2. Authentication Failed

Problem: Getting authentication errors
Solution:

• Verify NapCat service is running
• Check API Base URL is correct
• Ensure Access Token is valid (if required)

3. Message Sending Failed

Problem: Messages are not being sent
Solution:

• Verify User ID or Group ID is correct
• Check NapCat service logs
• Ensure the bot has proper permissions

4. Network Connection Issues

Problem: Cannot connect to NapCat API
Solution:

• Check network connectivity
• Verify firewall settings
• Ensure NapCat service is accessible

Debug Mode

Enable debug mode in n8n to see detailed logs:

1. Set environment variable: N8N_LOG_LEVEL=debug
2. Restart n8n
3. Check logs for detailed error information

🤝 Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

1. Check existing issues first
2. Create a new issue with detailed description
3. Include steps to reproduce the problem
4. Provide relevant logs and error messages

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests if applicable
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Write comprehensive tests
• Update documentation
• Follow the existing code style
• Ensure all tests pass

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NapCat - The amazing QQ bot framework
• n8n - The powerful workflow automation platform
• n8n Community - For inspiration and support

📞 Support

• Documentation: Check this README and the NapCat API docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Community: n8n Community Forum

🔄 Changelog

v1.0.0 (2024-01-XX)

• Initial release
• Support for private and group messaging
• Account information retrieval
• Basic error handling and validation

---

Made with ❤️ for the n8n and NapCat communities