@kichat/n8n-nodes-kirimchat 1.0.0

package/README.md

@@ -0,0 +1,145 @@
+# n8n-nodes-kirimchat
+
+This is an n8n community node for [KirimChat](https://kirim.chat) - a messaging platform that integrates WhatsApp Business API and Instagram DM.
+
+## Features
+
+- **Send Message** - Send text, image, document, audio, video, or template messages via WhatsApp or Instagram
+- **Mark as Read** - Mark messages as read and send read receipts
+- **Send Typing Indicator** - Show typing indicator to customers
+
+## Installation
+
+### Community Nodes (Recommended)
+
+1. Go to **Settings > Community Nodes**
+2. Select **Install**
+3. Enter `n8n-nodes-kirimchat` and confirm
+
+### Manual Installation
+
+```bash
+npm install n8n-nodes-kirimchat
+```
+
+## Credentials
+
+You need a KirimChat API key to use this node:
+
+1. Log in to your KirimChat dashboard
+2. Go to **Settings > Developers > API Keys**
+3. Click **Create API Key** and copy the key (shown only once)
+4. In n8n, create new credentials for **KirimChat API**
+5. Paste your API key (starts with `kc_live_`)
+
+## Operations
+
+### Send Message
+
+Send a message to a customer via WhatsApp or Instagram.
+
+| Parameter | Description |
+|-----------|-------------|
+| Customer ID | The ID of the customer (e.g., `cust_abc123`) |
+| Channel | `whatsapp` or `instagram` |
+| Message Type | `text`, `image`, `document`, `audio`, `video`, `template` (WhatsApp) or `text`, `image`, `media_share` (Instagram) |
+| Content | Text content for text messages |
+| Media URL | URL of media file for media messages |
+| Caption | Optional caption for media messages |
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "message_id": "msg_xyz789",
+    "status": "sent",
+    "channel": "whatsapp",
+    "timestamp": "2025-11-26T10:31:00.000Z"
+  }
+}
+```
+
+### Mark as Read
+
+Mark a message as read and send read receipt to the customer.
+
+| Parameter | Description |
+|-----------|-------------|
+| Message ID | The ID of the message to mark as read (e.g., `msg_xyz789`) |
+
+### Send Typing Indicator
+
+Show typing indicator to a customer before sending a message.
+
+| Parameter | Description |
+|-----------|-------------|
+| Customer ID | The ID of the customer |
+| Channel | `whatsapp` or `instagram` |
+
+> **Note:** Rate limited to 1 request per customer per 3 seconds.
+
+## Webhook Trigger
+
+KirimChat supports outbound webhooks for real-time event notifications. Configure webhooks in your KirimChat dashboard under **Settings > Developers > Webhooks**.
+
+### Supported Events
+
+- `message.received` - New message from customer
+- `message.sent` - Message sent to customer
+- `message.delivered` - Message delivered
+- `message.read` - Message read by customer
+- `message.failed` - Message delivery failed
+
+### Webhook Payload Example
+
+```json
+{
+  "event_type": "message.received",
+  "event_id": "evt_abc123",
+  "timestamp": "2025-11-26T10:30:00.000Z",
+  "data": {
+    "message_id": "msg_xyz789",
+    "customer_id": "cust_123",
+    "customer_phone": "+6281234567890",
+    "direction": "inbound",
+    "message_type": "text",
+    "content": "Hello!",
+    "channel": "whatsapp"
+  }
+}
+```
+
+### Using with n8n Webhook Node
+
+1. Create a new workflow with **Webhook** trigger node
+2. Copy the webhook URL
+3. In KirimChat, create a webhook endpoint with this URL
+4. Select the events you want to receive
+5. Connect the webhook to your KirimChat node for automated responses
+
+## Rate Limits
+
+- **Global:** 100 requests per minute per API key
+- **Send Message:** 60 messages per minute per API key
+- **Typing Indicator:** 1 request per customer per 3 seconds
+
+## Error Handling
+
+The node returns standard error responses:
+
+| Code | Description |
+|------|-------------|
+| 401 | Invalid or expired API key |
+| 404 | Resource not found |
+| 400 | Invalid request or messaging window closed |
+| 429 | Rate limit exceeded |
+
+## Resources
+
+- [KirimChat Documentation](https://kirim.chat/developers)
+- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)
+
+## License
+
+MIT

package/dist/credentials/KirimChatApi.credentials.d.ts

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

package/dist/credentials/KirimChatApi.credentials.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KirimChatApi = void 0;
+class KirimChatApi {
+    constructor() {
+        this.name = 'kirimChatApi';
+        this.displayName = 'KirimChat API';
+        this.documentationUrl = 'https://kirim.chat/developers';
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your KirimChat API key (starts with kc_live_)',
+                placeholder: 'kc_live_your_api_key_here',
+            },
+            {
+                displayName: 'API Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://api.paijoe.com/api/v1/public',
+                required: true,
+                description: 'The base URL for the KirimChat API',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/health',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.KirimChatApi = KirimChatApi;

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

@@ -0,0 +1,5 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class KirimChat implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/KirimChat/KirimChat.node.js

@@ -0,0 +1,424 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KirimChat = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+class KirimChat {
+    constructor() {
+        this.description = {
+            displayName: 'KirimChat',
+            name: 'kirimChat',
+            icon: 'file:kirimchat.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["operation"]}}',
+            description: 'Send WhatsApp & Instagram messages, mark as read, and send typing indicators',
+            defaults: {
+                name: 'KirimChat',
+            },
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [
+                {
+                    name: 'kirimChatApi',
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        {
+                            name: 'Send Message',
+                            value: 'sendMessage',
+                            description: 'Send a message to a customer via WhatsApp or Instagram',
+                            action: 'Send a message',
+                        },
+                        {
+                            name: 'Mark as Read',
+                            value: 'markAsRead',
+                            description: 'Mark a message as read',
+                            action: 'Mark a message as read',
+                        },
+                        {
+                            name: 'Send Typing Indicator',
+                            value: 'sendTyping',
+                            description: 'Send typing indicator to show you are typing',
+                            action: 'Send typing indicator',
+                        },
+                    ],
+                    default: 'sendMessage',
+                },
+                // Send Message Fields
+                {
+                    displayName: 'Customer ID',
+                    name: 'customerId',
+                    type: 'string',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                        },
+                    },
+                    default: '',
+                    description: 'The ID of the customer to send the message to',
+                    placeholder: 'cust_abc123',
+                },
+                {
+                    displayName: 'Channel',
+                    name: 'channel',
+                    type: 'options',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                        },
+                    },
+                    options: [
+                        {
+                            name: 'WhatsApp',
+                            value: 'whatsapp',
+                        },
+                        {
+                            name: 'Instagram',
+                            value: 'instagram',
+                        },
+                    ],
+                    default: 'whatsapp',
+                    description: 'The messaging channel to use',
+                },
+                {
+                    displayName: 'Message Type',
+                    name: 'messageType',
+                    type: 'options',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            channel: ['whatsapp'],
+                        },
+                    },
+                    options: [
+                        {
+                            name: 'Text',
+                            value: 'text',
+                        },
+                        {
+                            name: 'Image',
+                            value: 'image',
+                        },
+                        {
+                            name: 'Document',
+                            value: 'document',
+                        },
+                        {
+                            name: 'Audio',
+                            value: 'audio',
+                        },
+                        {
+                            name: 'Video',
+                            value: 'video',
+                        },
+                        {
+                            name: 'Template',
+                            value: 'template',
+                        },
+                    ],
+                    default: 'text',
+                    description: 'The type of message to send (WhatsApp)',
+                },
+                {
+                    displayName: 'Message Type',
+                    name: 'messageType',
+                    type: 'options',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            channel: ['instagram'],
+                        },
+                    },
+                    options: [
+                        {
+                            name: 'Text',
+                            value: 'text',
+                        },
+                        {
+                            name: 'Image',
+                            value: 'image',
+                        },
+                        {
+                            name: 'Media Share',
+                            value: 'media_share',
+                        },
+                    ],
+                    default: 'text',
+                    description: 'The type of message to send (Instagram)',
+                },
+                {
+                    displayName: 'Message Content',
+                    name: 'content',
+                    type: 'string',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            messageType: ['text'],
+                        },
+                    },
+                    default: '',
+                    description: 'The text content of the message',
+                    typeOptions: {
+                        rows: 4,
+                    },
+                },
+                {
+                    displayName: 'Media URL',
+                    name: 'mediaUrl',
+                    type: 'string',
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            messageType: ['image', 'document', 'audio', 'video', 'media_share'],
+                        },
+                    },
+                    default: '',
+                    description: 'URL of the media file to send',
+                },
+                {
+                    displayName: 'Caption',
+                    name: 'caption',
+                    type: 'string',
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            messageType: ['image', 'document', 'video'],
+                        },
+                    },
+                    default: '',
+                    description: 'Optional caption for media messages',
+                },
+                {
+                    displayName: 'Filename',
+                    name: 'filename',
+                    type: 'string',
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            messageType: ['document'],
+                        },
+                    },
+                    default: '',
+                    description: 'Filename for document messages',
+                    placeholder: 'invoice.pdf',
+                },
+                // Template fields (WhatsApp only)
+                {
+                    displayName: 'Template Name',
+                    name: 'templateName',
+                    type: 'string',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            messageType: ['template'],
+                        },
+                    },
+                    default: '',
+                    description: 'Name of the WhatsApp template to send',
+                    placeholder: 'hello_world',
+                },
+                {
+                    displayName: 'Template Language',
+                    name: 'templateLanguage',
+                    type: 'string',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            messageType: ['template'],
+                        },
+                    },
+                    default: 'en',
+                    description: 'Language code for the template',
+                    placeholder: 'en',
+                },
+                {
+                    displayName: 'Template Components (JSON)',
+                    name: 'templateComponents',
+                    type: 'json',
+                    displayOptions: {
+                        show: {
+                            operation: ['sendMessage'],
+                            messageType: ['template'],
+                        },
+                    },
+                    default: '[]',
+                    description: 'Template components as JSON array (for variables, buttons, etc.)',
+                },
+                // Mark as Read Fields
+                {
+                    displayName: 'Message ID',
+                    name: 'messageId',
+                    type: 'string',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['markAsRead'],
+                        },
+                    },
+                    default: '',
+                    description: 'The ID of the message to mark as read',
+                    placeholder: 'msg_xyz789',
+                },
+                // Send Typing Fields
+                {
+                    displayName: 'Customer ID',
+                    name: 'customerId',
+                    type: 'string',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendTyping'],
+                        },
+                    },
+                    default: '',
+                    description: 'The ID of the customer to send typing indicator to',
+                    placeholder: 'cust_abc123',
+                },
+                {
+                    displayName: 'Channel',
+                    name: 'channel',
+                    type: 'options',
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ['sendTyping'],
+                        },
+                    },
+                    options: [
+                        {
+                            name: 'WhatsApp',
+                            value: 'whatsapp',
+                        },
+                        {
+                            name: 'Instagram',
+                            value: 'instagram',
+                        },
+                    ],
+                    default: 'whatsapp',
+                    description: 'The messaging channel to use',
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const credentials = await this.getCredentials('kirimChatApi');
+        const baseUrl = credentials.baseUrl;
+        for (let i = 0; i < items.length; i++) {
+            try {
+                const operation = this.getNodeParameter('operation', i);
+                let responseData;
+                if (operation === 'sendMessage') {
+                    // Send Message Operation
+                    const customerId = this.getNodeParameter('customerId', i);
+                    const channel = this.getNodeParameter('channel', i);
+                    const messageType = this.getNodeParameter('messageType', i);
+                    const body = {
+                        customer_id: customerId,
+                        channel,
+                        message_type: messageType,
+                    };
+                    if (messageType === 'text') {
+                        body.content = this.getNodeParameter('content', i);
+                    }
+                    else if (messageType === 'template') {
+                        // WhatsApp template message
+                        const templateName = this.getNodeParameter('templateName', i);
+                        const templateLanguage = this.getNodeParameter('templateLanguage', i);
+                        const templateComponentsJson = this.getNodeParameter('templateComponents', i, '[]');
+                        let templateComponents = [];
+                        try {
+                            templateComponents = JSON.parse(templateComponentsJson);
+                        }
+                        catch {
+                            // Keep empty array if invalid JSON
+                        }
+                        body.template = {
+                            name: templateName,
+                            language: { code: templateLanguage },
+                            components: templateComponents,
+                        };
+                    }
+                    else {
+                        // Media messages
+                        body.media_url = this.getNodeParameter('mediaUrl', i, '');
+                        const caption = this.getNodeParameter('caption', i, '');
+                        if (caption) {
+                            body.caption = caption;
+                        }
+                        // Document filename
+                        if (messageType === 'document') {
+                            const filename = this.getNodeParameter('filename', i, '');
+                            if (filename) {
+                                body.filename = filename;
+                            }
+                        }
+                    }
+                    responseData = await this.helpers.httpRequestWithAuthentication.call(this, 'kirimChatApi', {
+                        method: 'POST',
+                        url: `${baseUrl}/messages/send`,
+                        body,
+                        json: true,
+                    });
+                }
+                else if (operation === 'markAsRead') {
+                    // Mark as Read Operation
+                    const messageId = this.getNodeParameter('messageId', i);
+                    responseData = await this.helpers.httpRequestWithAuthentication.call(this, 'kirimChatApi', {
+                        method: 'POST',
+                        url: `${baseUrl}/messages/${messageId}/read`,
+                        json: true,
+                    });
+                }
+                else if (operation === 'sendTyping') {
+                    // Send Typing Indicator Operation
+                    const customerId = this.getNodeParameter('customerId', i);
+                    const channel = this.getNodeParameter('channel', i);
+                    responseData = await this.helpers.httpRequestWithAuthentication.call(this, 'kirimChatApi', {
+                        method: 'POST',
+                        url: `${baseUrl}/conversations/${customerId}/typing`,
+                        body: { channel },
+                        json: true,
+                    });
+                }
+                else {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `The operation "${operation}" is not supported!`);
+                }
+                const executionData = this.helpers.constructExecutionMetaData(this.helpers.returnJsonArray(responseData), { itemData: { item: i } });
+                returnData.push(...executionData);
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    returnData.push({
+                        json: {
+                            error: errorMessage,
+                        },
+                        pairedItem: {
+                            item: i,
+                        },
+                    });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+exports.KirimChat = KirimChat;

package/dist/nodes/KirimChat/kirimchat.svg

@@ -0,0 +1,6 @@
+<svg width="60" height="60" viewBox="0 0 60 60" xmlns="http://www.w3.org/2000/svg">
+  <!-- Chat Bubble - White background with Black border -->
+  <path d="M3,9 Q3,3 9,3 H51 Q57,3 57,9 V42 Q57,48 51,48 H18 L3,57 V9 Z" fill="white" stroke="black" stroke-width="3"/>
+  <!-- Text - Black color -->
+  <text x="30" y="30" font-family="Arial, sans-serif" font-size="24" font-weight="900" fill="black" text-anchor="middle" dominant-baseline="middle">KC</text>
+</svg>

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@kichat/n8n-nodes-kirimchat",
+  "version": "1.0.0",
+  "description": "n8n community node for KirimChat - Send WhatsApp & Instagram messages, mark as read, and send typing indicators",
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "kirimchat",
+    "whatsapp",
+    "instagram",
+    "messaging",
+    "chat"
+  ],
+  "license": "MIT",
+  "homepage": "https://kirim.chat",
+  "author": {
+    "name": "KirimChat",
+    "email": "support@kirim.chat"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kirimchat/n8n-nodes-kirimchat.git"
+  },
+  "main": "dist/nodes/KirimChat/KirimChat.node.js",
+  "scripts": {
+    "build": "tsc && npm run copy-icons",
+    "copy-icons": "node -e \"require('fs').cpSync('nodes/KirimChat/kirimchat.svg', 'dist/nodes/KirimChat/kirimchat.svg')\"",
+    "dev": "tsc --watch",
+    "format": "prettier nodes credentials --write",
+    "lint": "eslint nodes credentials package.json",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/KirimChatApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/KirimChat/KirimChat.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "^7.0.0",
+    "copyfiles": "^2.4.1",
+    "eslint": "^8.0.0",
+    "n8n-workflow": "^1.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  }
+}