# 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()
```