@kirimchat/sdk

TypeScript SDK for KirimChat Public API - Send messages via WhatsApp, Instagram, and Messenger.

Features

✅ Full TypeScript support with auto-generated types
✅ WhatsApp, Instagram, and Messenger messaging
✅ Template messages with variables
✅ Interactive messages (buttons, lists)
✅ Customer management
✅ Native fetch API (Node.js 18+, browser)
✅ ESM + CJS dual build

Installation

npm install @kirimchat/sdk
# or
pnpm add @kirimchat/sdk
# or
yarn add @kirimchat/sdk

Requirements

• Node.js >= 18.0.0 (for native fetch support)
• KirimChat API key (get it from dashboard)

Quick Start

import { sendMessage, client } from '@kirimchat/sdk'

// Configure SDK
client.setConfig({
  baseUrl: 'https://api-prod.kirim.chat/api/v1/public',
  headers: {
    Authorization: 'Bearer kc_live_your_api_key_here'
  }
})

// Send a WhatsApp message
const result = await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'text',
    content: 'Hello from KirimChat SDK!'
  }
})

console.log('Message sent:', result)

Usage

Configuration

import { client } from '@kirimchat/sdk'

client.setConfig({
  baseUrl: 'https://api-prod.kirim.chat/api/v1/public',
  headers: {
    Authorization: 'Bearer kc_live_your_api_key_here',
    'X-Custom-Header': 'value' // Optional: additional headers
  }
})

Customer Management

import { createCustomer, getCustomerById, getCustomerByPhone, listCustomers } from '@kirimchat/sdk'

// Create a customer
const customer = await createCustomer({
  body: {
    phone_number: '628123456789',
    name: 'John Doe',
    consent_status: true,
    tags: ['lead', 'website']
  }
})

// Get customer by ID
const customerById = await getCustomerById({
  path: { customerId: 'clxxx1234567890' }
})

// Get customer by phone number
const customerByPhone = await getCustomerByPhone({
  path: { phoneNumber: '628123456789' }
})

// List customers with filters
const customers = await listCustomers({
  query: {
    page: 1,
    limit: 20,
    consent_status: 'true',
    search: 'John',
    sort_by: 'created_at',
    sort_order: 'desc'
  }
})

Sending Messages

Text Message

import { sendMessage } from '@kirimchat/sdk'

await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'text',
    content: 'Hello, how can I help you?'
  }
})

Media Message

await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'image',
    media_url: 'https://example.com/image.jpg',
    caption: 'Check out our latest product!'
  }
})

Interactive Message (Buttons)

await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'interactive',
    interactive: {
      type: 'button',
      body: { text: 'How would you rate our service?' },
      action: {
        buttons: [
          { type: 'reply', reply: { id: 'good', title: 'Good' } },
          { type: 'reply', reply: { id: 'ok', title: 'Okay' } },
          { type: 'reply', reply: { id: 'bad', title: 'Bad' } }
        ]
      }
    }
  }
})

Interactive Message (List)

await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'interactive',
    interactive: {
      type: 'list',
      body: { text: 'Please select a service' },
      action: {
        button: 'View Menu',
        sections: [
          {
            title: 'Services',
            rows: [
              { id: 'haircut', title: 'Haircut', description: 'Basic haircut' },
              { id: 'coloring', title: 'Hair Coloring', description: 'Full color' }
            ]
          }
        ]
      }
    }
  }
})

Template Message

await sendMessage({
  body: {
    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' }
          ]
        }
      ]
    }
  }
})

Message Status

import { getMessageStatus, markMessageAsRead } from '@kirimchat/sdk'

// Get message status
const status = await getMessageStatus({
  path: { messageId: 'msg_xyz789' }
})

// Mark message as read
await markMessageAsRead({
  path: { messageId: 'msg_xyz789' }
})

Typing Indicator

import { sendTypingIndicator } from '@kirimchat/sdk'

// Send typing indicator
await sendTypingIndicator({
  path: { customerIdentifier: '628123456789' },
  body: {
    channel: 'whatsapp'
  }
})

Templates

import { listTemplates, getTemplate } from '@kirimchat/sdk'

// List templates
const templates = await listTemplates({
  query: {
    status: 'APPROVED',
    category: 'MARKETING',
    limit: 100
  }
})

// Get specific template
const template = await getTemplate({
  path: { templateId: 'tmpl_xyz789' }
})

Connected Accounts

import { listInstagramAccounts, listMessengerPages } from '@kirimchat/sdk'

// List Instagram accounts
const igAccounts = await listInstagramAccounts()

// List Facebook Pages (Messenger)
const fbPages = await listMessengerPages()

Error Handling

import { sendMessage } from '@kirimchat/sdk'

try {
  await sendMessage({
    body: {
      phone_number: '628123456789',
      channel: 'whatsapp',
      message_type: 'text',
      content: 'Hello!'
    }
  })
} catch (error) {
  console.error('API Error:', error)
}

Examples

See the examples directory for more usage examples:

• basic-usage.ts - Health check and listing customers
• send-message.ts - Sending text, media, and interactive messages
• customer-management.ts - Creating and managing customers
• template-message.ts - Sending WhatsApp template messages

API Reference

Full API documentation: https://docs.kirim.chat

Development

# Install dependencies
pnpm install

# Generate SDK from OpenAPI spec
pnpm generate

# Type check
pnpm typecheck

# Build
pnpm build

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT © KirimChat

Support

• Documentation: https://docs.kirim.chat
• Email: [email protected]
• Website: https://kirim.chat