Developer

Developer API & Webhooks

Copy page

KirimChat menyediakan Public API dan Webhooks untuk integrasi dengan sistem eksternal seperti CRM, e-commerce, atau automation tools.

Overview

Fitur Developer

Fitur	Deskripsi
API Keys	Autentikasi untuk akses API
Public API	REST API untuk kirim pesan, manage customer
Webhooks	Notifikasi real-time untuk events
Event Logs	Monitoring dan debugging

Subscription Requirement

API Keys

API Key digunakan untuk autentikasi saat mengakses Public API.

Membuat API Key

1. Buka Developers > API Keys
2. Klik Create API Key
3. Isi nama untuk identifikasi
4. Pilih expiration (1-365 hari)
5. Klik Create
6. Copy dan simpan key - hanya ditampilkan sekali!

Format API Key

Code
 
kc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Status API Key

Status	Deskripsi
Active	Key aktif dan bisa digunakan
Expiring	Akan expired dalam 30 hari
Expired	Sudah tidak bisa digunakan

Revoke API Key

1. Temukan key di daftar
2. Klik Revoke
3. Konfirmasi
4. Key langsung tidak aktif

Batasan

• Maksimal 5 API keys per user
• Expiration: 1-365 hari
• Tidak bisa melihat full key setelah dibuat

Autentikasi API

Semua request ke Public API harus menyertakan header:

Code
 
Authorization: Bearer kc_live_xxxxx

Contoh Request

Code
 
curl -X POST https://api-prod.kirim.chat/api/v1/public/messages/send \
  -H "Authorization: Bearer kc_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "628123456789",
    "channel": "whatsapp",
    "message_type": "text",
    "content": "Hello World"
  }'

Public API Endpoints

Base URL: https://api-prod.kirim.chat/api/v1/public

Endpoint Overview

Endpoint	Method	Deskripsi
/health	GET	Health check & verifikasi API key
/customers	POST	Buat customer baru
/customers	GET	List customers dengan filter & pagination
/customers/{customerId}	GET	Get customer by ID
/customers/phone/{phoneNumber}	GET	Get customer by phone number
/messages/send	POST	Kirim pesan (text, template, media, interactive)
/messages/{messageId}/status	GET	Cek status pesan
/messages/{messageId}/read	POST	Mark message as read
/conversations/{customerIdentifier}/typing	POST	Kirim typing indicator
/templates	GET	List WhatsApp templates
/templates/{templateId}	GET	Get template by ID
/accounts/instagram	GET	List connected Instagram accounts
/accounts/messenger	GET	List connected Facebook Pages

Contoh: Send Text Message

Code
 
{
  "phone_number": "628123456789",
  "channel": "whatsapp",
  "message_type": "text",
  "content": "Hello from KirimChat API!"
}

Contoh: Send Template Message

Code
 
{
  "phone_number": "628123456789",
  "channel": "whatsapp",
  "message_type": "template",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John Doe" },
          { "type": "text", "text": "INV-12345" }
        ]
      }
    ]
  }
}

Contoh: Send Media Message

Code
 
{
  "phone_number": "628123456789",
  "channel": "whatsapp",
  "message_type": "image",
  "media_url": "https://example.com/image.jpg",
  "caption": "Check out this image!"
}

Response Format

Code
 
{
  "success": true,
  "data": {
    "message_id": "msg_xyz789",
    "status": "sent",
    "channel": "whatsapp"
  }
}

Rate Limits

Channel	Limit
WhatsApp	60 msg/min
Instagram	180 msg/hour
Messenger	180 msg/hour
Typing Indicator	1 req/3 sec per customer

Error Responses

Code
 
{
  "error": {
    "code": "ValidationError",
    "message": "Invalid phone number format",
    "details": "Phone number must be in E.164 format"
  }
}

Error Codes

Code	HTTP	Deskripsi
ValidationError	400	Input tidak valid
NotFound	404	Resource tidak ditemukan
Unauthorized	401	API key invalid
Forbidden	403	Tidak punya akses
RateLimitExceeded	429	Rate limit tercapai
WindowClosed	400	Jendela 24 jam tertutup
ConfigurationError	400	Channel tidak terkonfigurasi
InternalError	500	Server error

Webhooks

Webhooks mengirim notifikasi real-time ke endpoint Anda saat event terjadi.

Membuat Webhook

1. Buka Developers > Webhooks
2. Klik Create Webhook
3. Isi:
   • Name - Nama untuk identifikasi
   • URL - Endpoint HTTPS Anda
   • Events - Event yang ingin disubscribe
   • Channels - Channel filter (opsional)
4. Klik Create
5. Simpan secret - untuk verifikasi signature

Event Types

Event	Deskripsi
message.received	Pesan masuk dari customer
message.sent	Pesan berhasil dikirim
message.delivered	Pesan sampai ke device
message.read	Pesan dibaca customer
message.failed	Pengiriman pesan gagal

Channel Filter

• whatsapp - Hanya event WhatsApp
• instagram - Hanya event Instagram
• messenger - Hanya event Messenger
• all - Semua channel

Webhook Payload

Code
 
{
  "event_type": "message.received",
  "event_id": "uuid-xxx-xxx",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "customer_id": "cust_xxx",
    "customer_phone": "6281234567890",
    "direction": "inbound",
    "message_type": "text",
    "content": "Hello",
    "channel": "whatsapp"
  }
}

Signature Verification

Setiap request webhook menyertakan header signature:

Code
 
X-KirimChat-Signature: sha256=xxxxxx

Verifikasi dengan HMAC-SHA256:

Code
 
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

Test Webhook

1. Buka webhook yang sudah dibuat
2. Klik Test
3. Endpoint akan menerima test payload
4. Lihat response status dan latency

Delivery Logs

Lihat history pengiriman webhook:

• Timestamp
• Event type
• Response status
• Latency
• Error message (jika gagal)
• Retry count

Retention: 7 hari

Retry Policy

Jika webhook gagal (non-2xx response):

• Retry hingga 5 kali
• Exponential backoff
• Webhook di-disable setelah consecutive failures

Mengedit Webhook

1. Klik webhook dari daftar
2. Edit URL, events, atau channels
3. Save

Menghapus Webhook

1. Klik ikon delete
2. Konfirmasi
3. Webhook langsung tidak aktif

Batasan

• Maksimal 3 webhook endpoints per user
• URL harus HTTPS (HTTP hanya untuk development)
• Timeout: 10 detik

Integrasi Tools

n8n

1. Install n8n
2. Buat workflow baru
3. Gunakan HTTP Request node
4. Masukkan API key di header Authorization

Zapier

1. Buat Zap baru
2. Gunakan Webhook trigger untuk menerima event
3. Gunakan HTTP action untuk kirim pesan

Custom Integration

Gunakan library HTTP di bahasa pemrograman Anda:

• Node.js: axios, fetch
• Python: requests
• PHP: Guzzle
• Go: net/http

Best Practices

API Keys

1. Jangan expose - Simpan di environment variable
2. Rotate berkala - Buat key baru dan revoke yang lama
3. Monitor usage - Cek last used timestamp
4. Separate keys - Gunakan key berbeda untuk environment berbeda

Webhooks

1. Respond cepat - Return 200 dalam kurang dari 5 detik
2. Process async - Queue heavy processing
3. Verify signature - Selalu validasi signature
4. Handle duplicates - Gunakan event_id untuk dedup
5. Monitor logs - Cek delivery logs secara berkala

Error Handling

1. Implement retry - Untuk transient errors
2. Log errors - Untuk debugging
3. Alert on failures - Notifikasi jika banyak error
4. Graceful degradation - Handle API downtime

Contoh Kode

Node.js

Code
 
const axios = require('axios');

const API_KEY = process.env.KIRIMCHAT_API_KEY;
const BASE_URL = 'https://api-prod.kirim.chat/api/v1/public';

async function sendWhatsAppMessage(phoneNumber, message) {
  const response = await axios.post(
    `${BASE_URL}/messages/send`,
    {
      phone_number: phoneNumber,
      channel: 'whatsapp',
      message_type: 'text',
      content: message
    },
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

Python

Code
 
import requests
import os

API_KEY = os.environ['KIRIMCHAT_API_KEY']
BASE_URL = 'https://api-prod.kirim.chat/api/v1/public'

def send_whatsapp_message(phone_number, message):
    response = requests.post(
        f'{BASE_URL}/messages/send',
        json={
            'phone_number': phone_number,
            'channel': 'whatsapp',
            'message_type': 'text',
            'content': message
        },
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    return response.json()