n8n-nodes-sendzen 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 WhatsAble
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+# n8n-nodes-sendzen
+
+This is an n8n community node. It lets you use SendZen in your n8n workflows.
+
+SendZen is a platform for automating SMS and WhatsApp messages. This node package allows you to integrate SendZen's WhatsApp Cloud API capabilities directly into your n8n automation workflows, enabling you to send messages, manage templates, and handle incoming messages seamlessly.
+
+[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.
+
+[Installation](#installation)  
+[Operations](#operations)  
+[Credentials](#credentials)  
+[Compatibility](#compatibility)  
+[Usage](#usage)  
+[Resources](#resources)  
+[Version history](#version-history)
+
+---
+
+## Installation
+
+Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.
+
+---
+
+## Operations
+
+### SendZen Node (Action Node)
+
+The SendZen action node supports the following operations:
+
+#### Send Session Message
+Send a free-form text message to a WhatsApp recipient. This operation allows you to send messages within an active 24-hour conversation window.
+
+**Features:**
+- Send text messages with optional URL preview
+- Support for E.164 phone number format
+- Automatic phone number validation
+
+**Required Fields:**
+- WABA Account: Select your WhatsApp Business Account
+- Recipient Phone Number: Phone number in E.164 format (e.g., +1234567890)
+- Reply Message: The message text to send
+
+**Optional Fields:**
+- Enable URL Preview: Automatically generate link previews for URLs in the message
+
+#### Send Template Message
+Send a pre-approved WhatsApp message template to recipients. Templates are required for initiating conversations outside the 24-hour window or for sending structured messages.
+
+**Features:**
+- Dynamic template variable mapping
+- Support for templates with headers, body, buttons, and carousels
+- Automatic template discovery from your WABA account
+- Resource mapper for easy variable mapping
+
+**Required Fields:**
+- WABA Account: Select your WhatsApp Business Account
+- Recipient Phone Number: Phone number in E.164 format
+- Template: Select from your approved templates
+- Template Variables: Map values to template variables (automatically detected)
+
+**Template Support:**
+- Text headers with variables
+- Body text with variables
+- Media headers (Image, Video, Document)
+- Interactive buttons (URL, Quick Reply, Flow)
+- Carousel components
+
+#### Mark as Read
+Mark an incoming message as read. This operation helps maintain proper message status tracking in your WhatsApp conversations.
+
+**Features:**
+- Automatic message ID detection from trigger data
+- Automatic phone number ID detection
+- Manual override options for both IDs
+
+**Required Fields:**
+- Phone Number ID: Automatically detected from trigger, or manually specified
+- Message ID: Automatically detected from trigger, or manually specified
+
+#### Show Typing Indicator
+Display a typing indicator to the recipient, indicating that a response is being prepared.
+
+**Features:**
+- Automatic message ID detection from trigger data
+- Automatic phone number ID detection
+- Manual override options for both IDs
+
+**Required Fields:**
+- Phone Number ID: Automatically detected from trigger, or manually specified
+- Message ID: Automatically detected from trigger, or manually specified
+
+### SendZen Trigger Node
+
+The SendZen trigger node allows you to receive incoming WhatsApp messages in real-time.
+
+**Features:**
+- Webhook-based message reception
+- Automatic workflow activation on message receipt
+- Full message payload passed to workflow
+
+**Setup:**
+1. Add the SendZen Trigger node to your workflow
+2. Copy the webhook URL from the node
+3. Configure the webhook URL in your SendZen dashboard
+4. Activate the workflow to start receiving messages
+
+---
+
+## Credentials
+
+To use the SendZen nodes, you need to authenticate with your SendZen API key.
+
+### Prerequisites
+
+1. **Sign up for SendZen**
+   - Visit [SendZen Website](https://www.sendzen.io/)
+   - [Create an account](https://app.sendzen.io/signup) or [log in to your existing account](https://app.sendzen.io/login)
+
+2. **Get Your API Key**
+   - Navigate to your SendZen dashboard
+   - Go to API Keys section
+   - Generate or copy your API key
+   - Keep your API key secure and never share it publicly
+
+3. **Set Up WhatsApp Business Account (WABA)**
+   - Connect your WhatsApp Business Account in SendZen
+   - Complete Meta's business verification if required
+   - Ensure your WABA accounts are properly configured
+
+### Setting Up Credentials in n8n
+
+1. **Create New Credential**
+   - In the SendZen node settings, click on "Credentials"
+   - Select "Create New" or "New Credential"
+   - Choose "SendZen API" from the credential type list
+
+2. **Enter Your API Key**
+   - Paste your SendZen API key in the "API Key" field
+   - Optionally enable "Return Full Response" if you need complete HTTP response details
+   - Give your credential a descriptive name (e.g., "SendZen Production")
+
+3. **Save and Test**
+   - Click "Save" to store your credentials
+   - Test the connection by selecting a WABA account in the node
+
+> **Security Note:** Your API key is stored securely in n8n's credential system. Never commit API keys to version control or share them publicly.
+
+---
+
+## Compatibility
+
+- **Minimum n8n version:** 1.0.0
+- **Node.js version:** >=18.10
+- **Tested with n8n:** 1.89.2+
+
+This node is compatible with all n8n versions that support community nodes and the n8n Nodes API version 1.
+
+---
+
+## Usage
+
+### Basic Workflow: Send a Session Message
+
+1. **Create a new workflow** in n8n
+2. **Add a trigger node** (e.g., Manual Trigger, Webhook, Schedule)
+3. **Add the SendZen node**
+4. **Configure the node:**
+   - Select your SendZen API credentials
+   - Choose "Send Session Message" as the operation
+   - Select your WABA Account
+   - Enter the recipient phone number (E.164 format: +1234567890)
+   - Enter your message text
+   - Optionally enable URL preview
+5. **Test and activate** your workflow
+
+### Advanced Workflow: Send Template Message with Variables
+
+1. **Set up your template** in SendZen/Meta Business Manager
+2. **Create a workflow** with a trigger (e.g., form submission, database update)
+3. **Add the SendZen node**
+4. **Configure the node:**
+   - Select "Send Template Message" operation
+   - Choose your WABA Account
+   - Select your template from the dropdown
+   - Use the Resource Mapper to map template variables:
+     - Body variables (e.g., `{{1}}`, `{{2}}`)
+     - Header variables (if applicable)
+     - Button variables (if applicable)
+     - Media URLs (for media headers)
+5. **Map your data** from previous nodes to template variables
+6. **Test and activate** your workflow
+
+### Incoming Message Workflow
+
+1. **Add the SendZen Trigger node** to your workflow
+2. **Copy the webhook URL** from the node
+3. **Configure webhook in SendZen:**
+   - Go to your SendZen dashboard
+   - Navigate to Webhooks settings
+   - Paste the webhook URL
+   - Save the configuration
+4. **Add action nodes** to process incoming messages:
+   - Use "Mark as Read" to acknowledge messages
+   - Use "Show Typing Indicator" to show you're responding
+   - Use "Send Session Message" to reply
+5. **Activate the workflow** to start receiving messages
+
+### Phone Number Format
+
+All phone numbers must be in **E.164 format**:
+- Start with `+` followed by country code
+- Include area code and number
+- Example: `+1234567890` (US), `+447911123456` (UK)
+
+The node automatically adds the `+` prefix if missing, but you should ensure the full number including country code is provided.
+
+### Template Variables
+
+When using template messages, the node automatically detects variables in your templates:
+- **Body variables:** Detected from `{{1}}`, `{{2}}`, etc. in template body
+- **Header variables:** Detected from `{{1}}` in text headers
+- **Button variables:** Detected from URL or text parameters in buttons
+- **Media headers:** Require a media URL to be provided
+
+Use the Resource Mapper feature to easily map your workflow data to template variables.
+
+---
+
+## Resources
+
+* [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
+* [SendZen Documentation](https://sendzen.io/docs)
+* [SendZen Website](https://www.sendzen.io/)
+* [n8n Documentation](https://docs.n8n.io)
+* [WhatsApp Business Platform Documentation](https://developers.facebook.com/docs/whatsapp)
+
+---
+
+## Version history
+
+### Version 1.0.0
+- Initial release
+- Support for sending session messages
+- Support for sending template messages with dynamic variables
+- Support for marking messages as read
+- Support for showing typing indicators
+- Webhook trigger for incoming messages
+- Automatic WABA account discovery
+- Automatic template discovery
+- Resource mapper for template variables
+- Support for templates with headers, body, buttons, and carousels
+
+---
+
+## Running Locally
+
+To run and test this node on your local machine:
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/sendzen-io/n8n-nodes-sendzen.git
+   cd n8n-nodes-sendzen
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pnpm install
+   ```
+
+3. **Build the project**
+   ```bash
+   pnpm build
+   ```
+
+4. **Run tests**
+   ```bash
+   pnpm test
+   ```
+
+5. **Link the node to your local n8n instance**
+   - Follow [n8n's community node development guide](https://docs.n8n.io/integrations/community-nodes/create/)
+   - Typically, you can run:
+     ```bash
+     pnpm link --global
+     cd ~/.n8n/custom
+     pnpm link --global n8n-nodes-sendzen
+     ```
+   - Restart your n8n instance to load the custom node
+
+6. **Test your node**
+   - Open n8n in your browser (usually at `http://localhost:5678`)
+   - Create a workflow and add your custom node to test its functionality
+
+> **Note:** Make sure you have [Node.js](https://nodejs.org/) (>=18.10) and [pnpm](https://pnpm.io/) installed on your machine.
+
+---
+
+## Contributing
+
+We welcome contributions from the community! To contribute:
+
+1. **Fork the repository**: [https://github.com/sendzen-io/n8n-nodes-sendzen](https://github.com/sendzen-io/n8n-nodes-sendzen)
+2. **Create a new branch** for your feature or bugfix:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. **Make your changes** and ensure code quality:
+   - Follow the existing code style
+   - Add or update documentation as needed
+   - Run linter and tests before submitting
+   ```bash
+   pnpm lint
+   pnpm test
+   ```
+4. **Commit your changes**
+   ```bash
+   git commit -m "Add your message here"
+   ```
+5. **Push to your fork**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+6. **Open a Pull Request**
+   - Go to the GitHub page for your fork
+   - Click "Compare & pull request"
+   - Describe your changes and submit the PR
+
+### Reporting Issues
+
+If you find a bug or have a feature request, please [open an issue](https://github.com/sendzen-io/n8n-nodes-sendzen/issues) with:
+- Detailed description of the issue
+- Steps to reproduce
+- Expected vs actual behavior
+- n8n version and node version
+- Any relevant error messages or logs
+
+### Code of Conduct
+
+Please be respectful and follow our [Code of Conduct](CODE_OF_CONDUCT.md) when participating in this project.
+
+---
+
+## License
+
+[MIT](LICENSE.md)
+
+---
+
+## Support
+
+For technical support and assistance:
+
+- **Documentation**: Visit [SendZen Documentation](https://sendzen.io/docs)
+- **Email Support**: Contact support at milan@sendzen.io
+- **GitHub Issues**: [Report issues](https://github.com/sendzen-io/n8n-nodes-sendzen/issues)
+
+For enterprise-level support or custom solutions, contact the SendZen team.
+

package/dist/credentials/SendZenApi.credentials.d.ts

@@ -0,0 +1,8 @@
+import { IAuthenticateGeneric, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class SendZenApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+}

package/dist/credentials/SendZenApi.credentials.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendZenApi = void 0;
+class SendZenApi {
+    constructor() {
+        this.name = 'sendZenApi';
+        this.displayName = 'SendZen API';
+        this.documentationUrl = 'https://sendzen.io/docs';
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+            },
+            {
+                displayName: 'Return Full Response',
+                name: 'returnFullResponse',
+                type: 'boolean',
+                default: false,
+                description: 'If enabled, the full HTTP response will be returned including the status code, headers, and body.',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+    }
+}
+exports.SendZenApi = SendZenApi;
+//# sourceMappingURL=SendZenApi.credentials.js.map

package/dist/credentials/SendZenApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SendZenApi.credentials.js","sourceRoot":"","sources":["../../credentials/SendZenApi.credentials.ts"],"names":[],"mappings":";;;AAME,MAAa,UAAU;IAAvB;QACE,SAAI,GAAG,YAAY,CAAC;QACpB,gBAAW,GAAG,aAAa,CAAC;QAC5B,qBAAgB,GAAG,yBAAyB,CAAC;QAE7C,eAAU,GAAsB;YAC9B;gBACE,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;aACZ;YACJ;gBACC,WAAW,EAAE,sBAAsB;gBACnC,IAAI,EAAE,oBAAoB;gBAC1B,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,KAAK;gBACd,WAAW,EAAE,mGAAmG;aAChH;SACC,CAAC;QAEF,iBAAY,GAAyB;YACnC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACV,OAAO,EAAE;oBACT,aAAa,EAAE,iCAAiC;iBAC/C;aACF;SACF,CAAC;IACJ,CAAC;CAAA;AA9BD,gCA8BC"}

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

@@ -0,0 +1,14 @@
+import { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription, ResourceMapperFields } from 'n8n-workflow';
+export declare class SendZen implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getTemplates(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getWabaAccounts(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+        resourceMapping: {
+            getTemplateVariables(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}