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