Merge pull request #473 from moltis-org/bloom-porcupine

fix(whatsapp): improve discoverability and debug logging

Author: penso

crates/config/src/template.rs

@@ -581,6 +581,20 @@ reset_on_exit = true              # Reset serve/funnel when gateway shuts down
 # External messaging integrations.
 
 [channels]
+# Which channel types appear in the web UI's "+ Add Channel" menu.
+# Default: ["telegram", "discord", "slack"]
+# Add "whatsapp" or "msteams" to enable them in the UI.
+# offered = ["telegram", "discord", "slack", "whatsapp"]
+
+# WhatsApp linked-device accounts
+# [channels.whatsapp.my-bot]
+# dm_policy = "open"              # "open", "allowlist", or "disabled"
+# group_policy = "disabled"       # "open", "allowlist", or "disabled"
+# model = "anthropic/claude-sonnet-4-20250514"
+# model_provider = "anthropic"
+# otp_self_approval = true        # OTP self-approval for non-allowlisted DM users
+# otp_cooldown_secs = 300         # Cooldown after 3 failed OTP attempts
+
 # Telegram bots
 # [channels.telegram.my-bot]
 # token = "..."                   # Bot token from @BotFather

crates/whatsapp/src/handlers.rs

@@ -396,6 +396,13 @@ async fn handle_message(
             handle_location(&msg, account_id, reply_to, meta, chat_jid, state).await;
         },
         ChannelMessageKind::Other => {
+            info!(
+                account_id = %state.account_id,
+                chat = %chat_jid,
+                "unhandled WhatsApp message type — replying with error. \
+                 Message fields present: {}",
+                describe_message_fields(&msg),
+            );
             let reply_msg = wa::Message {
                 conversation: Some(
                     "Sorry, I can't understand that message type. Check logs for details.".into(),
@@ -717,6 +724,42 @@ fn is_owner_user(jid: &Jid, own_pn: Option<&Jid>, own_lid: Option<&Jid>) -> bool
         || own_lid.is_some_and(|lid| lid.is_same_user_as(jid))
 }
 
+/// List which `Option` fields on `wa::Message` are `Some`, giving operators a
+/// concrete clue about the unhandled message type (e.g. "sticker_message, reaction_message").
+///
+/// Only checks fields that are NOT already handled by `classify_message` to avoid
+/// misleading output — if a field appears here it genuinely was not dispatched.
+fn describe_message_fields(msg: &wa::Message) -> String {
+    let mut present = Vec::new();
+    macro_rules! check {
+        ($($field:ident),+ $(,)?) => {
+            $(if msg.$field.is_some() { present.push(stringify!($field)); })+
+        };
+    }
+    // Omit fields already handled by classify_message:
+    //   conversation, extended_text_message, image_message, audio_message,
+    //   video_message, document_message, location_message, live_location_message
+    check!(
+        sender_key_distribution_message,
+        contact_message,
+        call,
+        protocol_message,
+        contacts_array_message,
+        sticker_message,
+        reaction_message,
+        poll_creation_message,
+        poll_update_message,
+        interactive_message,
+        edited_message,
+        event_message,
+    );
+    if present.is_empty() {
+        "none".to_owned()
+    } else {
+        present.join(", ")
+    }
+}
+
 /// Classify the inbound message kind based on its content.
 ///
 /// Media types take priority over text — an image with a caption is still `Photo`,
@@ -949,4 +992,39 @@ mod tests {
         assert!(is_self_chat);
         assert!(!sender_is_owner);
     }
+
+    #[test]
+    fn describe_message_fields_reports_present_fields() {
+        let msg = wa::Message {
+            sticker_message: Some(Default::default()),
+            reaction_message: Some(Default::default()),
+            ..Default::default()
+        };
+        let desc = describe_message_fields(&msg);
+        assert!(
+            desc.contains("sticker_message"),
+            "expected sticker_message in: {desc}"
+        );
+        assert!(
+            desc.contains("reaction_message"),
+            "expected reaction_message in: {desc}"
+        );
+    }
+
+    #[test]
+    fn describe_message_fields_empty_message_returns_none() {
+        let msg = wa::Message::default();
+        assert_eq!(describe_message_fields(&msg), "none");
+    }
+
+    #[test]
+    fn describe_message_fields_excludes_handled_types() {
+        // image_message is handled by classify_message — should NOT appear
+        let msg = wa::Message {
+            image_message: Some(Default::default()),
+            ..Default::default()
+        };
+        let desc = describe_message_fields(&msg);
+        assert_eq!(desc, "none", "handled fields should not appear: {desc}");
+    }
 }

docs/src/whatsapp.md

@@ -51,6 +51,19 @@ whatsapp = ["moltis-gateway/whatsapp"]
 When disabled, all WhatsApp code is compiled out — no QR code library, no
 Signal Protocol store, no WhatsApp event handlers.
 
+```admonish important title="Enable in Channel List"
+WhatsApp is not shown in the web UI by default. Add it to the offered
+channels list in `moltis.toml`:
+
+\`\`\`toml
+[channels]
+offered = ["telegram", "discord", "slack", "whatsapp"]
+\`\`\`
+
+Restart Moltis after changing this setting. The **+ Add Channel** menu
+will then include the WhatsApp option.
+```
+
 ## Quick Start (Web UI)
 
 The fastest way to connect WhatsApp:
@@ -336,6 +349,21 @@ Switch to the **Senders** tab to see everyone who has messaged the bot:
 
 ## Troubleshooting
 
+### WhatsApp Not in Add Channel Menu
+
+- WhatsApp is not offered by default. Add `"whatsapp"` to the `offered` list in `moltis.toml`:
+  ```toml
+  [channels]
+  offered = ["telegram", "discord", "slack", "whatsapp"]
+  ```
+- Restart Moltis after changing this setting
+
+### "Can't Understand That Message Type"
+
+- This means the bot received a message type it doesn't handle (e.g. stickers, reactions, polls)
+- Check the server logs for an `info` entry that lists which message fields were present
+- Supported types: text, images, audio, voice notes, video, documents, and locations
+
 ### QR Code Not Appearing
 
 - Ensure the `whatsapp` feature is enabled (it is by default)