{"id":28427839,"url":"https://github.com/peaktwilight/thatsappmqttdebugger","last_synced_at":"2026-04-30T20:31:54.136Z","repository":{"id":294017149,"uuid":"985672867","full_name":"peaktwilight/ThatsAppMQTTDebugger","owner":"peaktwilight","description":"A feature-rich MQTT debugging tool for ThatsApp messaging protocol development and testing. Connect to brokers, subscribe to topics, publish messages, and monitor real-time communication.","archived":false,"fork":false,"pushed_at":"2026-01-12T21:40:32.000Z","size":1288,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T01:55:27.001Z","etag":null,"topics":["debugging-tool","developer-tools","iot","messaging","mqtt","mqtt-broker","mqtt-client","nextjs","react","websockets"],"latest_commit_sha":null,"homepage":"https://thatsapp.doruk.ch","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peaktwilight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2025-05-18T09:29:33.000Z","updated_at":"2026-01-12T21:40:48.000Z","dependencies_parsed_at":"2025-07-02T21:05:26.227Z","dependency_job_id":"f20a23c4-a0b4-4552-a322-380a91a7b4fd","html_url":"https://github.com/peaktwilight/ThatsAppMQTTDebugger","commit_stats":null,"previous_names":["peaktwilight/thatsappmqttdebugger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/peaktwilight/ThatsAppMQTTDebugger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peaktwilight%2FThatsAppMQTTDebugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peaktwilight%2FThatsAppMQTTDebugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peaktwilight%2FThatsAppMQTTDebugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peaktwilight%2FThatsAppMQTTDebugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peaktwilight","download_url":"https://codeload.github.com/peaktwilight/ThatsAppMQTTDebugger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peaktwilight%2FThatsAppMQTTDebugger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32476682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["debugging-tool","developer-tools","iot","messaging","mqtt","mqtt-broker","mqtt-client","nextjs","react","websockets"],"created_at":"2025-06-05T12:30:35.033Z","updated_at":"2026-04-30T20:31:54.121Z","avatar_url":"https://github.com/peaktwilight.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ThatsApp MQTT Debugger\n\nA feature-rich MQTT debugging tool designed specifically for ThatsApp messaging protocol development and testing. This web-based application allows you to easily connect to MQTT brokers, subscribe to topics, publish messages, and monitor real-time communication.\n\n![ThatsApp MQTT Debugger](public/MQTT.png)\n\n## 🔗 Live Demo\n\nTry it now: [thatsapp.doruk.ch](https://thatsapp.doruk.ch)\n\n## 🚀 Features\n\n### Connection \u0026 Subscription\n- **Connect to any MQTT broker** with WebSocket support (ws:// or wss://)\n- **Subscribe to multiple topics** with support for wildcards\n- **Visual connection status** with real-time indicator\n\n### Message Publishing\n- **Publish messages** with customizable payload and retained flag\n- **ThatsApp message templates** for quick testing with proper JSON formatting\n- **Support for all message types**:\n  - Text messages\n  - Image messages\n  - Location sharing\n  - Profile updates and requests\n  - Typing indicators\n  - Online status polls and responses\n- **JSON formatting** with automatic validation\n\n### Real-time Message Viewing\n- **Interactive message display** with syntax highlighting and formatting\n- **Message type detection** with appropriate icons and styling\n- **Retained message indicators** for distinguishing standard and retained messages\n- **Message filtering** by topic to focus on specific communication\n- **Duplicate detection** to clean up repetitive messages\n- **Auto-scroll toggle** to follow new messages or pause to inspect\n- **New message notifications** when scrolled away from latest messages\n- **Animation effects** for new messages with visual indicators\n- **Smooth performance** even with high message volumes\n\n### User Interface\n- **Responsive design** that works on all devices (desktop, tablet, mobile)\n- **Collapsible filters** for a cleaner interface\n- **Interactive components** with hover and animation effects\n- **Consistent spacing** and visual hierarchy\n- **Custom scrollbars** for better usability\n- **High-performance animations** using Framer Motion\n\n### Developer Tools\n- **Message Types Guide** with comprehensive protocol documentation\n- **Copy-paste example code** for each message type\n- **Implementation notes** to ensure cross-client compatibility\n- **Common mistakes documentation** to avoid protocol errors\n- **Topic structure guide** for proper addressing\n\n## 📋 Detailed Usage Guide\n\n### MQTT Connection\n\n#### Establishing a Connection\n\n1. When you first open the debugger, you'll see the MQTT Connection panel\n2. The default broker URL is set to `ws://broker.hivemq.com:8000/mqtt` (a public test broker)\n3. A random client ID is generated for you automatically\n4. Click the \"Connect\" button to establish a connection\n\n#### Connection Security\n\n- When using the tool on an HTTPS site, it will automatically upgrade WebSocket connections to secure WSS\n- The connection status indicator shows green when connected and red when disconnected\n- The connection pulses to indicate active connection status\n\n#### Custom Brokers\n\nYou can connect to any MQTT broker that supports WebSocket connections:\n\n- Public brokers like HiveMQ, Mosquitto, or EMQ X\n- Self-hosted brokers with WebSocket enabled\n- Cloud MQTT services (ensure they support WebSockets)\n\n### Topic Subscription\n\n#### Subscribing to Topics\n\n1. After connecting, use the Topic Subscriptions panel\n2. Enter a topic or topic pattern in the input field\n   - Example: `thatsapp/publictest/#` to subscribe to all ThatsApp public test messages\n   - Example: `thatsapp/publictest/user123/messages` for a specific user's messages\n3. Click \"Subscribe\" to add the subscription\n4. The topic appears in the list below with an option to unsubscribe\n\n#### Using Wildcards\n\nMQTT supports two wildcards:\n- Single-level (`+`): Matches exactly one topic level\n  - Example: `thatsapp/+/messages` matches `thatsapp/user1/messages` but not `thatsapp/user1/inbox/messages`\n- Multi-level (`#`): Matches any number of topic levels (must be the last character)\n  - Example: `thatsapp/#` matches all topics that start with `thatsapp/`\n\n#### Managing Subscriptions\n\n- You can subscribe to multiple topics simultaneously\n- Each subscription is listed with an unsubscribe button\n- Clicking the unsubscribe button immediately removes that subscription\n\n### Publishing Messages\n\n#### Basic Message Publishing\n\n1. Use the Publish Message panel to send messages\n2. Enter the destination topic (e.g., `thatsapp/publictest/user456/messages`)\n3. Toggle \"Format as JSON\" if sending structured data\n4. Toggle \"Retained\" if the message should be stored on the broker\n5. Enter your message payload in the text area\n6. Click \"Publish\" to send the message\n\n#### Using ThatsApp Templates\n\nFor ThatsApp-specific messages:\n\n1. Ensure \"Format as JSON\" is toggled on\n2. Fill in the Sender ID (your identifier)\n3. Fill in the Recipient ID (target user or \"global\")\n4. Select a message type from the dropdown\n5. Click \"Create Template\" to generate a template message\n6. Edit the template as needed\n7. Click \"Publish\" to send\n\n#### Message Types\n\nThe debugger supports all ThatsApp message types:\n\n1. **TEXT**: Simple text messages\n   - Payload is the message text itself\n   - Example: `\"Hello, how are you?\"`\n\n2. **IMAGE**: Image sharing\n   - Payload is the URL to the image\n   - Example: `\"https://example.com/images/photo.jpg\"`\n\n3. **LOCATION**: Geographic location sharing\n   - Payload is a JSON object with latitude and longitude\n   - Example: `{\"latitude\": 47.3769, \"longitude\": 8.5417}`\n\n4. **PROFILE_UPDATE**: User profile information\n   - Payload is a JSON object with name and optional avatarUrl\n   - Example: `{\"name\": \"John Doe\", \"avatarUrl\": \"https://example.com/avatar.jpg\"}`\n\n5. **REQUEST_PROFILE**: Request for profile information\n   - Payload is typically empty\n   - Used to ask another user to send their profile\n\n6. **TYPING**: Typing indicator\n   - Payload is typically empty\n   - Indicates a user is currently typing\n\n7. **ONLINE_POLL**: Check who's online\n   - Payload contains sender information\n   - Sent to the global topic to discover online users\n\n8. **ONLINE_RESPONSE**: Response to online poll\n   - Payload contains responder information\n   - Sent to the global topic when responding to a poll\n\n### Message Viewer\n\n#### Viewing Messages\n\nThe Message Viewer panel displays all received messages based on your subscriptions:\n\n- Messages are displayed in chronological order (newest at the bottom)\n- Each message shows the topic, timestamp, and formatted content\n- JSON messages are automatically formatted and syntax-highlighted\n- ThatsApp messages are formatted according to their type\n- Retained messages are marked with a \"Retained\" label\n\n#### Display Controls\n\nSeveral controls enhance the viewing experience:\n\n- **Auto-scroll**: Toggle to automatically scroll to new messages (off by default)\n- **Filter duplicates**: Toggle to hide duplicate messages within a short timeframe\n- **Filter**: Click the filter icon to show/hide topic filtering options\n- **Clear**: Remove all messages from the viewer\n\n#### Message Animations\n\n- New messages feature a subtle highlight animation\n- When scrolled away from the bottom, a \"New messages\" indicator appears\n- Click the indicator to instantly scroll to the newest messages\n\n#### Performance Optimizations\n\n- The viewer uses virtualization for handling large message volumes\n- Animations are throttled during high-volume message periods\n- Maximum message count is limited to ensure performance\n\n### Message Types Guide\n\nAccess the Message Types Guide by clicking the button in the top-right header.\n\n#### Guide Features\n\n- **Message Types Overview**: Details about each supported message type\n- **Recipient Standards**: How to properly address messages\n- **Implementation Notes**: Best practices for ThatsApp protocol\n- **Common Mistakes**: Issues to avoid when implementing clients\n- **Topic Structure**: Standard topic hierarchy for ThatsApp\n\n#### Example Code\n\nEach message type includes an example code section:\n\n1. Click \"View Example Code\" to show the example\n2. Examples include proper JSON formatting with comments\n3. Click the copy icon to copy the example to clipboard\n4. Use examples as templates for your own messages\n\n### Tips and Tricks\n\n#### Efficient Testing\n\n- Use the \"Create Template\" button to quickly generate valid messages\n- Subscribe to `thatsapp/publictest/#` to see all public test messages\n- Use \"Filter duplicates\" when testing with multiple clients to reduce noise\n- Turn off Auto-scroll when examining specific messages\n\n#### Working with Retained Messages\n\n- Use retained messages to persist state information\n- Publishing an empty retained message clears previously retained messages\n- The \"Retained\" chip helps identify which messages are persisted\n\n#### Message Debugging\n\n- Use topic filters to focus on specific communication channels\n- Examine timestamps to understand message sequence\n- Check message formatting to ensure protocol compliance\n- Compare sent and received messages to verify correct transmission\n\n### Troubleshooting\n\n#### Connection Issues\n\n- Ensure the broker URL is correct and includes the WebSocket protocol (ws:// or wss://)\n- Check that the broker supports WebSockets on the specified port\n- Try a different client ID if you suspect ID conflicts\n- Verify network connectivity and firewall settings\n\n#### Message Problems\n\n- Verify JSON syntax if messages aren't being properly formatted\n- Check topic spelling and structure\n- Ensure payload format matches the specified message type\n- Verify that recipients are specified correctly for direct messages\n\n#### Performance Considerations\n\n- Limit subscriptions to necessary topics\n- Use specific topic patterns instead of broad wildcards\n- Enable \"Filter duplicates\" to reduce message volume\n- Clear the message viewer periodically during long sessions\n\n## 💻 Development\n\nThe project is built with:\n\n- **Next.js** - React framework for web applications\n- **React** - UI library\n- **TypeScript** - Type-safe JavaScript\n- **Material UI** - Component library\n- **Framer Motion** - Animation library\n- **Paho MQTT** - MQTT client library for browser\n\n### Project Structure\n\n```\n/\n├── components/          # React components\n│   ├── ConnectionForm.tsx\n│   ├── MessagePublisher.tsx\n│   ├── MessageViewer.tsx\n│   ├── MessageTypesGuide.tsx\n│   └── TopicSubscriber.tsx\n├── contexts/            # React contexts\n│   └── MQTTContext.tsx  # MQTT client management\n├── lib/                 # Utility functions\n│   └── messageTemplates.ts\n├── pages/               # Next.js pages\n│   ├── _app.tsx\n│   ├── _document.tsx\n│   └── index.tsx        # Main application page\n├── public/              # Static assets\n├── styles/              # CSS styles\n└── types/               # TypeScript type definitions\n```\n\n### Running Locally\n\n```bash\n# Clone the repository\ngit clone https://github.com/peaktwilight/ThatsAppMQTTDebugger.git\n\n# Navigate to the project directory\ncd ThatsAppMQTTDebugger\n\n# Install dependencies\nnpm install\n\n# Start the development server\nnpm run dev\n```\n\n### Building for Production\n\n```bash\nnpm run build\nnpm start\n```\n\n## 📱 ThatsApp Message Protocol\n\nThatsApp uses a simple JSON message format for communication:\n\n```typescript\ninterface ThatsAppMessage {\n  senderId: string;      // Unique ID of the sender\n  recipientId: string;   // Unique ID of the recipient or \"global\"\n  timestamp: number;     // Message timestamp in milliseconds\n  type: string;          // Message type (TEXT, IMAGE, LOCATION, etc.)\n  payload: string;       // Message content (format depends on type)\n}\n```\n\n### Message Types\n\nThe debugger supports all ThatsApp message types:\n\n| Type | Description | Payload Format | Usage |\n|------|-------------|---------------|-------|\n| TEXT | Regular text messages | String | Direct |\n| IMAGE | Image URL messages | URL String | Direct |\n| LOCATION | Location data | JSON with latitude, longitude | Direct |\n| PROFILE_UPDATE | Profile information | JSON with name, avatarUrl | Direct/Global |\n| REQUEST_PROFILE | Profile information request | Empty string | Direct/Global |\n| TYPING | Typing indicators | Empty string | Direct |\n| ONLINE_POLL | Request to check who's online | JSON with name, avatarUrl | Global |\n| ONLINE_RESPONSE | Response to an online poll | JSON with name, avatarUrl | Global |\n\n### Topic Structure\n\n- **Global messages**: `thatsapp/publictest/global`\n- **Direct messages**: `thatsapp/publictest/{recipientId}/messages`\n\n## 🔒 Security Considerations\n\n- The app runs entirely in your browser and does not store any data on a server\n- Your MQTT connection details and messages are not saved between sessions\n- When using the tool on an HTTPS page, it will automatically upgrade insecure WebSocket connections to secure ones (WSS)\n\n## 🚨 Error Handling\n\nThe debugger includes comprehensive error handling to help identify and resolve issues:\n\n- **Connection Errors**: Detailed error messages when connection fails, including broker URL validation\n- **Operation Errors**: Clear notifications about failures in subscriptions, publications, and message processing\n- **Input Validation**: Safeguards against empty topics, malformed messages, and invalid JSON\n- **Persistent Connection**: Automatic reconnection attempts when connections drop unexpectedly\n- **Visual Indicators**: Error messages are displayed prominently to help users identify and fix problems\n- **WebSocket Security**: Automatic protocol upgrade from ws:// to wss:// when using HTTPS\n\n## 📄 License\n\nThis project is licensed under the ISC License.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeaktwilight%2Fthatsappmqttdebugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeaktwilight%2Fthatsappmqttdebugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeaktwilight%2Fthatsappmqttdebugger/lists"}