mqtt
This commit is contained in:
370
MQTT_CONFIG_EXAMPLE.md
Normal file
370
MQTT_CONFIG_EXAMPLE.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# MQTT Configuration Example
|
||||
|
||||
This document provides examples of how to configure MQTT support in whatshooked.
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
Add the following to your `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"event_logger": {
|
||||
"enabled": true,
|
||||
"targets": ["mqtt"],
|
||||
"mqtt": {
|
||||
"broker": "tcp://localhost:1883",
|
||||
"client_id": "whatshooked-mqtt",
|
||||
"username": "your_mqtt_username",
|
||||
"password": "your_mqtt_password",
|
||||
"topic_prefix": "whatshooked",
|
||||
"qos": 1,
|
||||
"retained": false,
|
||||
"events": [
|
||||
"message.received",
|
||||
"message.sent",
|
||||
"whatsapp.connected",
|
||||
"whatsapp.disconnected"
|
||||
],
|
||||
"subscribe": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Fields
|
||||
|
||||
### Required Fields
|
||||
|
||||
- **broker**: MQTT broker URL (e.g., `tcp://localhost:1883`, `ssl://broker.example.com:8883`)
|
||||
|
||||
### Optional Fields
|
||||
|
||||
- **client_id**: MQTT client identifier (auto-generated if not specified)
|
||||
- **username**: Username for MQTT broker authentication
|
||||
- **password**: Password for MQTT broker authentication
|
||||
- **topic_prefix**: Prefix for all MQTT topics (default: `whatshooked`)
|
||||
- **qos**: Quality of Service level (0, 1, or 2; default: 1)
|
||||
- 0: At most once delivery
|
||||
- 1: At least once delivery
|
||||
- 2: Exactly once delivery
|
||||
- **retained**: Whether messages should be retained by the broker (default: false)
|
||||
- **events**: Array of event types to publish. If empty or omitted, all events will be published.
|
||||
- **subscribe**: Enable subscription for sending WhatsApp messages via MQTT (default: false)
|
||||
|
||||
## Topic Structure
|
||||
|
||||
### Published Events
|
||||
|
||||
Events are published to topics in the format:
|
||||
```
|
||||
{topic_prefix}/{account_id}/{event_type}
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `whatshooked/my-account/message.received`
|
||||
- `whatshooked/my-account/whatsapp.connected`
|
||||
- `whatshooked/business-account/message.sent`
|
||||
|
||||
### Sending Messages (Subscribe Mode)
|
||||
|
||||
When `subscribe: true` is enabled, you can send WhatsApp messages by publishing to:
|
||||
```
|
||||
{topic_prefix}/{account_id}/send
|
||||
```
|
||||
|
||||
#### Text Messages
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "text",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"text": "Hello from MQTT!"
|
||||
}
|
||||
```
|
||||
|
||||
#### Image Messages (via URL)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "image",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"url": "https://example.com/image.jpg",
|
||||
"caption": "Check out this image!",
|
||||
"mime_type": "image/jpeg"
|
||||
}
|
||||
```
|
||||
|
||||
#### Image Messages (via Base64)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "image",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
|
||||
"caption": "A small test image",
|
||||
"mime_type": "image/png"
|
||||
}
|
||||
```
|
||||
|
||||
#### Video Messages (via URL)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "video",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"url": "https://example.com/video.mp4",
|
||||
"caption": "Check out this video!",
|
||||
"mime_type": "video/mp4"
|
||||
}
|
||||
```
|
||||
|
||||
#### Document Messages (via URL)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "document",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"url": "https://example.com/report.pdf",
|
||||
"filename": "monthly-report.pdf",
|
||||
"caption": "Here's the monthly report",
|
||||
"mime_type": "application/pdf"
|
||||
}
|
||||
```
|
||||
|
||||
#### Document Messages (via Base64)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "document",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"base64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c...",
|
||||
"filename": "document.pdf",
|
||||
"caption": "Important document",
|
||||
"mime_type": "application/pdf"
|
||||
}
|
||||
```
|
||||
|
||||
**Payload Fields:**
|
||||
- `type`: Message type - "text", "image", "video", or "document" (default: "text")
|
||||
- `to`: Phone number in JID format (required)
|
||||
- `text`: Message text (required for text messages)
|
||||
- `caption`: Optional caption for media messages
|
||||
- `mime_type`: MIME type of the media (defaults: image/jpeg, video/mp4, application/pdf)
|
||||
- `filename`: Filename for documents (required for document type)
|
||||
- `base64`: Base64 encoded media data (mutually exclusive with `url`)
|
||||
- `url`: URL to download media from (mutually exclusive with `base64`)
|
||||
|
||||
**Note:** For media messages, you must provide either `base64` or `url`, but not both.
|
||||
|
||||
## Event Types
|
||||
|
||||
Available event types for filtering:
|
||||
|
||||
### WhatsApp Connection Events
|
||||
- `whatsapp.connected`
|
||||
- `whatsapp.disconnected`
|
||||
- `whatsapp.pair.success`
|
||||
- `whatsapp.pair.failed`
|
||||
- `whatsapp.qr.code`
|
||||
- `whatsapp.qr.timeout`
|
||||
- `whatsapp.qr.error`
|
||||
- `whatsapp.pair.event`
|
||||
|
||||
### Message Events
|
||||
- `message.received`
|
||||
- `message.sent`
|
||||
- `message.failed`
|
||||
- `message.delivered`
|
||||
- `message.read`
|
||||
|
||||
### Hook Events
|
||||
- `hook.triggered`
|
||||
- `hook.success`
|
||||
- `hook.failed`
|
||||
|
||||
## Home Assistant Integration Example
|
||||
|
||||
To integrate with Home Assistant, you can use the MQTT integration:
|
||||
|
||||
```yaml
|
||||
# configuration.yaml
|
||||
mqtt:
|
||||
sensor:
|
||||
- name: "WhatsApp Status"
|
||||
state_topic: "whatshooked/my-account/whatsapp.connected"
|
||||
value_template: "{{ value_json.type }}"
|
||||
|
||||
- name: "Last WhatsApp Message"
|
||||
state_topic: "whatshooked/my-account/message.received"
|
||||
value_template: "{{ value_json.data.text }}"
|
||||
json_attributes_topic: "whatshooked/my-account/message.received"
|
||||
json_attributes_template: "{{ value_json.data | tojson }}"
|
||||
|
||||
# Send messages from Home Assistant
|
||||
script:
|
||||
send_whatsapp_text:
|
||||
sequence:
|
||||
- service: mqtt.publish
|
||||
data:
|
||||
topic: "whatshooked/my-account/send"
|
||||
payload: '{"type": "text", "to": "27821234567@s.whatsapp.net", "text": "Alert from Home Assistant!"}'
|
||||
|
||||
send_whatsapp_image:
|
||||
sequence:
|
||||
- service: mqtt.publish
|
||||
data:
|
||||
topic: "whatshooked/my-account/send"
|
||||
payload: >
|
||||
{
|
||||
"type": "image",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"url": "https://example.com/camera-snapshot.jpg",
|
||||
"caption": "Motion detected at front door"
|
||||
}
|
||||
|
||||
send_whatsapp_camera_snapshot:
|
||||
sequence:
|
||||
# Take a snapshot
|
||||
- service: camera.snapshot
|
||||
target:
|
||||
entity_id: camera.front_door
|
||||
data:
|
||||
filename: /tmp/snapshot.jpg
|
||||
# Convert to base64 and send via MQTT
|
||||
- service: mqtt.publish
|
||||
data:
|
||||
topic: "whatshooked/my-account/send"
|
||||
payload: >
|
||||
{
|
||||
"type": "image",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"base64": "{{ state_attr('camera.front_door', 'entity_picture') | base64_encode }}",
|
||||
"caption": "Front door snapshot"
|
||||
}
|
||||
|
||||
send_whatsapp_document:
|
||||
sequence:
|
||||
- service: mqtt.publish
|
||||
data:
|
||||
topic: "whatshooked/my-account/send"
|
||||
payload: >
|
||||
{
|
||||
"type": "document",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"url": "https://example.com/daily-report.pdf",
|
||||
"filename": "daily-report.pdf",
|
||||
"caption": "Today's energy usage report"
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Configuration Example
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"host": "0.0.0.0",
|
||||
"port": 8080
|
||||
},
|
||||
"whatsapp": [
|
||||
{
|
||||
"id": "my-account",
|
||||
"type": "whatsmeow",
|
||||
"phone_number": "27821234567",
|
||||
"session_path": "./data/sessions/my-account",
|
||||
"show_qr": true
|
||||
}
|
||||
],
|
||||
"media": {
|
||||
"data_path": "./data/media",
|
||||
"mode": "link"
|
||||
},
|
||||
"event_logger": {
|
||||
"enabled": true,
|
||||
"targets": ["file", "mqtt"],
|
||||
"file_dir": "./data/events",
|
||||
"mqtt": {
|
||||
"broker": "tcp://homeassistant.local:1883",
|
||||
"username": "mqtt_user",
|
||||
"password": "mqtt_password",
|
||||
"topic_prefix": "whatshooked",
|
||||
"qos": 1,
|
||||
"retained": false,
|
||||
"events": [
|
||||
"message.received",
|
||||
"message.sent",
|
||||
"whatsapp.connected",
|
||||
"whatsapp.disconnected"
|
||||
],
|
||||
"subscribe": true
|
||||
}
|
||||
},
|
||||
"log_level": "info"
|
||||
}
|
||||
```
|
||||
|
||||
## Testing MQTT Connection
|
||||
|
||||
You can test your MQTT connection using `mosquitto_sub` and `mosquitto_pub`:
|
||||
|
||||
```bash
|
||||
# Subscribe to all whatshooked events
|
||||
mosquitto_sub -h localhost -t "whatshooked/#" -v
|
||||
|
||||
# Subscribe to specific account events
|
||||
mosquitto_sub -h localhost -t "whatshooked/my-account/#" -v
|
||||
|
||||
# Send a test text message
|
||||
mosquitto_pub -h localhost -t "whatshooked/my-account/send" \
|
||||
-m '{"type": "text", "to": "27821234567@s.whatsapp.net", "text": "Test message"}'
|
||||
|
||||
# Send an image from URL
|
||||
mosquitto_pub -h localhost -t "whatshooked/my-account/send" \
|
||||
-m '{"type": "image", "to": "27821234567@s.whatsapp.net", "url": "https://picsum.photos/200", "caption": "Random image"}'
|
||||
|
||||
# Send an image from base64 (1x1 red pixel example)
|
||||
mosquitto_pub -h localhost -t "whatshooked/my-account/send" \
|
||||
-m '{"type": "image", "to": "27821234567@s.whatsapp.net", "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==", "caption": "Red pixel"}'
|
||||
|
||||
# Send a document from URL
|
||||
mosquitto_pub -h localhost -t "whatshooked/my-account/send" \
|
||||
-m '{"type": "document", "to": "27821234567@s.whatsapp.net", "url": "https://example.com/document.pdf", "filename": "test.pdf", "caption": "Test document"}'
|
||||
|
||||
# Send a video from URL
|
||||
mosquitto_pub -h localhost -t "whatshooked/my-account/send" \
|
||||
-m '{"type": "video", "to": "27821234567@s.whatsapp.net", "url": "https://example.com/video.mp4", "caption": "Test video"}'
|
||||
```
|
||||
|
||||
### Using Python for Testing
|
||||
|
||||
```python
|
||||
import paho.mqtt.client as mqtt
|
||||
import json
|
||||
import base64
|
||||
|
||||
# Connect to broker
|
||||
client = mqtt.Client()
|
||||
client.connect("localhost", 1883, 60)
|
||||
|
||||
# Send text message
|
||||
payload = {
|
||||
"type": "text",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"text": "Hello from Python!"
|
||||
}
|
||||
client.publish("whatshooked/my-account/send", json.dumps(payload))
|
||||
|
||||
# Send image from file
|
||||
with open("image.jpg", "rb") as f:
|
||||
image_data = base64.b64encode(f.read()).decode()
|
||||
|
||||
payload = {
|
||||
"type": "image",
|
||||
"to": "27821234567@s.whatsapp.net",
|
||||
"base64": image_data,
|
||||
"caption": "Image from Python",
|
||||
"mime_type": "image/jpeg"
|
||||
}
|
||||
client.publish("whatshooked/my-account/send", json.dumps(payload))
|
||||
|
||||
client.disconnect()
|
||||
```
|
||||
Reference in New Issue
Block a user