@jep182/n8n-nodes-whatsthat 0.4.3 → 0.5.1

package/README.md

@@ -1,125 +1,204 @@
 # @jep182/n8n-nodes-whatsthat
 
-WhatsThat is an n8n community package for sending WhatsApp messages, with multiple sessions.
+WhatsThat lets you connect one or more WhatsApp numbers inside n8n, link chats or groups with simple names, send messages, and react to incoming events.
 
-It lets you:
+In the n8n node picker, you will find:
 
-- manage multiple sessions and numbers
-- connect with pairing code or QR
-- discover chats and groups
-- link chats/groups to friendly aliases
-- send text, media, documents, reactions, contacts, locations, and polls
-- receive inbound events through a trigger node
+- `WhatsThat` actions
+- `WhatsThat Trigger`
 
-## Included Nodes
+You also need one credential:
 
-### `WhatsThat Session`
+- `WhatsThat Runtime`
 
-Use this node to:
+## Before You Start
 
-- connect a session
-- wait for a session to become connected
-- list sessions
-- inspect session status
-- disconnect a session
-- remove a session
+Create `WhatsThat Runtime` credentials and choose a persistent storage path, for example:
 
-When pairing is available, the node returns:
+```text
+/home/node/.n8n/whatsthat
+```
 
-- `pairingCode`
-- `qrCodeUrl`
-- `qr`
-- `qrDataUrl`
+This folder is used to store session files and local metadata.
 
-### `WhatsThat Targets`
+The action nodes all appear under the same name, `WhatsThat`, but with different purposes:
 
-Use this node to:
+- session actions
+- linked chat actions
+- message actions
 
-- list discovered chats and groups
-- list linked aliases
-- link a target to an alias
-- unlink an alias
+## How To Connect Your Number
 
-### `WhatsThat Message`
+1. Add a `WhatsThat` node.
+2. Choose the action for sessions.
+3. Set `Operation` to `Connect Session`.
+4. Fill in:
+   - `Session Name`: a stable internal name like `main-phone`
+   - `Display Name`: a friendly label like `Luca phone`
+   - `WhatsApp Number`: optional, only if you want a pairing code instead of relying only on QR
+5. Run the node.
+6. In the output, open `qrCodeUrl`.
 
-Use this node to send:
+Open `qrCodeUrl` as the standard and recommended way to connect the number.
 
-- text
-- image
-- video
-- audio
-- document
-- reaction
-- location
-- contact
-- poll
+Important:
 
-For images and videos, the node can decide internally whether to send them as:
+- open `qrCodeUrl` whenever possible
+- do not rely on `pairingCode`
+- `pairingCode` is not stable and may fail or stop working depending on the session state and device behavior
+- `qrDataUrl` is available only if you specifically need the raw embedded QR image data
 
-- native media
-- file/document attachment
+Example:
 
-### `WhatsThat Trigger`
+```text
+Session Name: main-phone
+Display Name: Luca phone
+WhatsApp Number: 393331234567
+```
 
-Use this node to listen for:
+## How To Wait Until The Number Is Fully Connected
 
-- incoming messages
-- your own sent messages
-- session pairing events
-- session connected/disconnected events
-- group updates
+After `Connect Session`, add another `WhatsThat` node:
 
-## How It Works
+1. Choose the action for sessions
+2. Set `Operation` to `Wait Until Connect`
+3. Use the same `Session Name`
+4. Choose how many seconds to wait in `Timeout Seconds`
 
-WhatsThat embeds Baileys directly in n8n.
+This second node waits for the already-started session to become fully connected.
 
-- session auth files are stored on disk
-- session metadata and linked targets are stored as local JSON files under the runtime storage path
+## How To Link A Group Or Chat Manually
 
-## Quick Start
+1. Add a `WhatsThat` node
+2. Choose the action for linked chats
+3. Start with `Operation = List Discovered Chats`
+4. Pick the chat or group you want to use
+5. Change to `Operation = Link Chat`
+6. Fill in:
+   - `Session Name`
+   - `Chat JID`
+   - `Linked Chat`: the simple name you want to use later, for example `support` or `team`
 
-1. Create `WhatsThat Runtime` credentials.
-2. Set a storage path, for example:
+Example:
 
 ```text
-/home/node/.n8n/whatsthat
+Linked Chat: support
 ```
 
-3. Add `WhatsThat Session`.
-4. Choose `Connect Session`, then provide:
-   - `Session ID (Internal)`: a stable unique ID such as `main-phone`
-   - `Label (Visible Name)`: a human-readable name such as `Luca personal phone`
-   - optional `Phone Number For Pairing`: full number with country code, digits only, without `00` or `+`
-5. Run the node and use the returned `pairingCode`, `qrCodeUrl`, or `qrDataUrl` to connect the device.
-6. Add another `WhatsThat Session` node with `Ensure Session`.
-7. Set `Return When` to `Connected` so the workflow waits until the already-started session finishes pairing.
-8. Use `WhatsThat Targets` to discover and link chats/groups.
-9. Use `WhatsThat Message` to send messages by alias or raw JID.
+After that, you can send messages by choosing that linked chat instead of writing the raw JID every time.
 
-Example workflow:
+## How To Link A Group Or Chat From WhatsApp
 
-- [`examples/register-number.workflow.json`](./examples/register-number.workflow.json)
+Use `WhatsThat Trigger`.
 
-## Media Delivery
+1. Add a `WhatsThat Trigger` node
+2. Select the same `Session Name`
+3. Set `Event` to `Link Chat Command`
+4. Leave the default command or change it
 
-For `Image` and `Video` messages:
+By default, users can send a message like:
 
-- `Native Media` sends them as normal media with preview
-- `As File` sends them as a document/file attachment
+```text
+/link-whatsthat support
+```
 
-## Notes
+If that message is sent inside a group or chat, WhatsThat links that conversation with alias `support`.
 
-- This package runs an active WebSocket client inside n8n.
-- For production, use persistent storage for the auth directory.
-- Use one n8n instance as the runtime owner for these sessions.
+This is useful when you want users to self-register a group without opening n8n.
 
-## Thanks
+## How To Send A Message To A Linked Chat
+
+1. Add a `WhatsThat` node
+2. Choose the action for sending messages
+3. Set `Session Name`
+4. Set `Send Message To` to `Linked Chat`
+5. Choose a linked chat from the dropdown
+6. Choose `Message Type`
+7. Write the message
+
+Example:
+
+```text
+Send Message To: Linked Chat
+Linked Chat: support
+Message Type: Text
+Message: Hello from n8n
+```
+
+## How To Send A Message To A Number
+
+1. Add a `WhatsThat` node
+2. Choose the action for sending messages
+3. Set `Send Message To` to `WhatsApp Number`
+4. Enter the number with country code, digits only, without `00` and without `+`
+
+Example:
+
+```text
+WhatsApp Number: 393331234567
+```
+
+## How To Send A Message To Yourself
 
-This project relies on [Baileys](https://github.com/WhiskeySockets/Baileys), the open-source TypeScript/Node.js library that powers the messaging client layer.
+1. Add a `WhatsThat` node
+2. Choose the action for sending messages
+3. Set `Send Message To` to `Yourself`
 
-Please review the Baileys project, its license, and its usage notes before running it in production:
+WhatsThat uses the number already connected for that session.
+
+This is useful for testing.
+
+## How To Send Media
+
+For images and videos you can choose:
+
+- `Native Media`
+- `As File`
+
+Use `Media URL` for the file you want to send.
+
+Examples:
+
+- send an image preview normally
+- send a PDF as a document
+- send a video as a file attachment
+
+## How To Receive Events
+
+Use `WhatsThat Trigger` when you want to react to:
+
+- incoming messages
+- your own sent messages
+- pairing events
+- connection events
+- group updates
+
+Common examples:
+
+- start a workflow when a message arrives
+- auto-link a chat with `/link-whatsthat support`
+- continue a workflow when a session becomes connected
+
+## Example Workflow
+
+You can import this example:
+
+- [`examples/register-number.workflow.json`](./examples/register-number.workflow.json)
+
+It shows the basic flow:
+
+1. `Connect Session`
+2. `Wait Until Connect`
+
+## Notes
+
+- Use one persistent n8n instance as the owner of these sessions
+- Keep the runtime storage path persistent
+- If n8n restarts, active in-memory sockets are restarted from the saved session files
+
+## Thanks
 
-- [Baileys repository](https://github.com/WhiskeySockets/Baileys)
+This project uses [Baileys](https://github.com/WhiskeySockets/Baileys).
 
 ## License
 

package/dist/nodes/WhatsThat/WhatsThat.node.d.ts

@@ -0,0 +1,10 @@
+import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class WhatsThat implements INodeType {
+    methods: {
+        loadOptions: {
+            getLinkedAliases(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+    };
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}