n8n-nodes-kirimchat

This is an n8n community node for KirimChat - 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):

[
  {
    "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:

[
  { "id": "yes", "title": "Yes" },
  { "id": "no", "title": "No" },
  { "id": "maybe", "title": "Maybe" }
]

Example Response:

{
  "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:

{
  "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:

{
  "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

{
  "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:

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
• n8n Community Nodes

License

MIT