whatshooked/MQTT_CONFIG_EXAMPLE.md

MQTT Configuration Example

This document provides examples of how to configure MQTT support in whatshooked.

Configuration Structure

Add the following to your config.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

{
  "type": "text",
  "to": "27821234567@s.whatsapp.net",
  "text": "Hello from MQTT!"
}

Image Messages (via URL)

{
  "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)

{
  "type": "image",
  "to": "27821234567@s.whatsapp.net",
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "caption": "A small test image",
  "mime_type": "image/png"
}

Video Messages (via URL)

{
  "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)

{
  "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)

{
  "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:

# 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

{
  "server": {
    "host": "0.0.0.0",
    "port": 8025
  },
  "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:

# 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

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