npm package: @kichat/n8n-nodes-kirimchat
Description: n8n community node for KirimChat - Send WhatsApp, Instagram & Messenger messages with interactive buttons, flexible customer lookup, and typing indicators
Author: KirimChat
Latest version: 1.3.7

# n8n-nodes-kirimchat

This is an n8n community node for [KirimChat](https://kirim.chat) - a messaging platform that integrates WhatsApp Business API, Instagram DM, and Facebook Messenger.

## Features

- **Send Message** - Send text, image, document, audio, video, template, or interactive messages via WhatsApp, Instagram, or Messenger
- **List Templates** - List all WhatsApp message templates with filtering
- **Get Template** - Get a specific template by ID
- **Mark as Read** - Mark messages as read and send read receipts
- **Send Typing Indicator** - Show typing indicator to customers
- **Flexible Customer Lookup** - Find customers by ID, phone number, or Instagram username

## Installation

### Community Nodes (Recommended)

1. Go to **Settings > Community Nodes**
2. Select **Install**
3. Enter `@kichat/n8n-nodes-kirimchat` and confirm

## 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, Instagram, or Messenger.

#### Customer Lookup Options

| Method | Description | Example |
|--------|-------------|---------|
| Customer ID | KirimChat customer ID | `cust_abc123` |
| Phone Number | Phone with country code | `+6281234567890` |
| Instagram Username | Instagram username | `johndoe` |

#### Channels & Message Types

| Channel | Message Types |
|---------|---------------|
| **WhatsApp** | `text`, `image`, `document`, `audio`, `video`, `template`, `interactive` |
| **Instagram** | `text`, `image`, `media_share` |
| **Messenger** | `text`, `image`, `video`, `audio`, `file` |

#### Parameters

| Parameter | Description |
|-----------|-------------|
| Customer Lookup | How to identify the customer |
| Channel | `whatsapp`, `instagram`, or `messenger` |
| Message Type | Type of message (varies by channel) |
| Content | Text content for text messages |
| Media URL | URL of media file for media messages |
| Caption | Optional caption for media messages |
| Filename | Filename for document/file messages |

#### WhatsApp Template Messages

Templates can be selected from a dropdown or entered manually.

| Parameter | Description |
|-----------|-------------|
| Template | Select from approved templates. Shows variable count e.g. `[2 var]` |
| Template Variables | Comma-separated values. Example: `John, ORD-123` |
| Enter Template Manually | Toggle to type template name/language |

**Example:**

Template: `Hello {{1}}, your order {{2}} is ready!`

Template Variables: `John, ORD-123`

Result: "Hello John, your order ORD-123 is ready!"

**Advanced (Manual Mode with JSON):**
```json
[
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "John" },
      { "type": "text", "text": "12345" }
    ]
  }
]
```

#### WhatsApp Interactive Messages

Send buttons with your messages:

**CTA URL Button:**
| Parameter | Description |
|-----------|-------------|
| Interactive Type | `cta_url` |
| Body Text | Main message text (max 1024 chars) |
| Header Text | Optional header (max 60 chars) |
| Footer Text | Optional footer (max 60 chars) |
| Button Text | Text on button (max 20 chars) |
| Button URL | URL to open |

**Reply Buttons:**
| Parameter | Description |
|-----------|-------------|
| Interactive Type | `button` |
| Body Text | Main message text |
| Buttons (JSON) | Array of 1-3 buttons |

**Example Reply Buttons:**
```json
[
  { "id": "yes", "title": "Yes" },
  { "id": "no", "title": "No" },
  { "id": "maybe", "title": "Maybe" }
]
```

**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`) |

### List Templates

List all WhatsApp message templates with optional filtering.

| Parameter | Description |
|-----------|-------------|
| Filter by Status | `All`, `APPROVED`, `PENDING`, or `REJECTED` |
| Filter by Category | `All`, `MARKETING`, `UTILITY`, or `AUTHENTICATION` |
| Limit | Maximum templates to return (1-500, default 100) |

**Example Response:**
```json
{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "tpl_abc123",
        "templateName": "order_confirmation",
        "language": "en",
        "status": "APPROVED",
        "category": "UTILITY",
        "content": "Your order {{1}} has been confirmed.",
        "headerType": "TEXT",
        "headerContent": "Order Update",
        "footerContent": "Thank you for shopping!",
        "variables": ["order_number"],
        "createdAt": "2025-01-15T10:00:00.000Z"
      }
    ],
    "total": 1
  }
}
```

### Get Template

Get a specific WhatsApp message template by ID.

| Parameter | Description |
|-----------|-------------|
| Template ID | The ID of the template (e.g., `tpl_abc123`) |

**Example Response:**
```json
{
  "success": true,
  "data": {
    "id": "tpl_abc123",
    "templateName": "order_confirmation",
    "language": "en",
    "status": "APPROVED",
    "category": "UTILITY",
    "content": "Your order {{1}} has been confirmed.",
    "headerType": "TEXT",
    "headerContent": "Order Update",
    "footerContent": "Thank you for shopping!",
    "buttons": [
      { "type": "URL", "text": "Track Order", "url": "https://..." }
    ],
    "variables": ["order_number"],
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
}
```

### Send Typing Indicator

Show typing indicator to a customer before sending a message.

| Parameter | Description |
|-----------|-------------|
| Customer Lookup | How to identify the customer |
| Customer ID/Phone/Username | Customer identifier |
| Channel | `whatsapp`, `instagram`, or auto-detect |

> **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 Headers

KirimChat sends the following headers with each webhook:

| Header | Description |
|--------|-------------|
| `X-KirimChat-Signature` | HMAC-SHA256 signature for verification |
| `X-KirimChat-Event` | Event type (e.g., `message.received`) |
| `X-KirimChat-Delivery` | Unique delivery ID |
| `X-KirimChat-Idempotency-Key` | Idempotency key for deduplication |

### 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"
  }
}
```

### Handling Duplicate Events

KirimChat implements server-side deduplication, but in rare cases (network retries), duplicates may occur. To handle this in n8n:

**Option 1: Use Idempotency Key (Recommended)**

1. Add a **Code** node after your Webhook trigger
2. Check if you've seen this idempotency key before:

```javascript
const idempotencyKey = $input.first().headers['x-kirimchat-idempotency-key'];
const eventId = $input.first().json.event_id;

// Use event_id or idempotency key to deduplicate
// Store in a Set, Redis, or database to track processed events
return $input.all();
```

**Option 2: Use message_id + event_type**

The combination of `data.message_id` + `event_type` is unique per event. Store these in your workflow state or external storage to detect duplicates.

### 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

| Limit Type | Rate |
|------------|------|
| Global | 100 requests per minute per API key |
| WhatsApp | 60 messages per minute |
| Instagram | 180 messages per hour |
| Messenger | 180 messages per hour |
| 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 |
| 403 | Account disconnected or forbidden |
| 404 | Resource not found |
| 400 | Invalid request or messaging window closed |
| 429 | Rate limit exceeded |

### Common Error Codes

| Error Code | Description |
|------------|-------------|
| `ValidationError` | Invalid input parameters |
| `WindowClosed` | 24-hour messaging window expired |
| `ConfigurationError` | Channel not configured |
| `ConnectionError` | Account disconnected |
| `RateLimitExceeded` | Too many requests |

## Changelog

### v1.2.0 (Latest)
- ✅ Added **Template Dropdown** - Select templates from dropdown (auto-loaded from API)
- ✅ Added **Simple Variables** - Add template variables without writing JSON
- ✅ Added **List Templates** operation - List all WhatsApp templates with filtering
- ✅ Added **Get Template** operation - Get template details by ID
- ✅ Filter templates by status (Approved, Pending, Rejected)
- ✅ Filter templates by category (Marketing, Utility, Authentication)
- ✅ Improved template UX - No more manual JSON for simple use cases

### v1.1.0
- ✅ Added Messenger channel support
- ✅ Added customer lookup by phone number and Instagram username
- ✅ Added WhatsApp Interactive messages (CTA URL buttons, Reply buttons)
- ✅ Improved typing indicator with flexible customer lookup
- ✅ Enhanced error messages

### v1.0.5
- Enhanced validation for media URLs
- Template components structure validation

### v1.0.1
- Initial security improvements
- JSON validation for templates
- Base URL security warning

## Resources

- [KirimChat Documentation](https://kirim.chat/developers)
- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)

## License

MIT