msgkit-client

Official TypeScript SDK for Msgkit — a self-hosted WhatsApp transport gateway.

Installation

npm install msgkit-client

Quick Start

import { createClient } from 'msgkit-client'

const msgkit = createClient('http://localhost:54321', 'msgkit_anon_xxx')

// Send a text message
const { messageId } = await msgkit.sendText('+212600000000', 'Hello world')

// Send a media message
await msgkit.sendMedia('+212600000000', { url: 'https://example.com/image.png' })

// Send a location
await msgkit.sendLocation('+212600000000', 33.5731, -7.5898, { name: 'Casablanca' })

// Show a typing indicator
await msgkit.setPresence('+212600000000', 'typing')

// List chats
const chats = await msgkit.getChats()

// Read a conversation thread and take it over
const conversations = await msgkit.listConversations()
const messages = await msgkit.getConversationMessages(conversations[0].id)
await msgkit.takeoverConversation(conversations[0].id, { actor: 'agent-1' })

// Download media a contact sent in (image/video/audio/document)
const media = await msgkit.getMedia('wamid.XXX')

API Reference

createClient(url, apiKey, options?)

Creates a new Msgkit client instance.

| Parameter | Type | Description | |-----------|------|-------------| | url | string | Base URL of your Msgkit instance | | apiKey | string | Your anon or service API key | | options.maxRetries | number | Max retries on transient errors (default: 3) | | options.retryDelay | number | Base delay in ms between retries (default: 500) | | options.timeout | number | Request timeout in ms (default: 10000) |

msgkit.health()

Instance-wide liveness check (no notion of a single connected phone number — an instance can host many projects, each with their own numbers).

• Returns: Promise<{ status: string; uptimeSeconds: number }>

msgkit.sendText(phone, text)

Send a text message to the given phone number.

• Returns: Promise<{ messageId?: string }>

msgkit.sendMedia(phone, options)

Send a media message. options is SendMediaOptions: { kind?: MediaKind; url?: string; base64?: string; caption?: string; filename?: string } — provide either url or base64. kind is 'image' | 'video' | 'audio' | 'document', defaulting to 'image'; filename only matters for 'document'.

• Returns: Promise<{ messageId?: string }>

msgkit.sendLocation(phone, latitude, longitude, options?)

Send a WhatsApp location message. options is { name?: string; address?: string }, both optional.

• Returns: Promise<{ messageId?: string }>

msgkit.getChats()

List the WhatsApp contacts visible to the connected number.

• Returns: Promise<Chat[]> — each Chat is { jid: string; name?: string }

msgkit.setPresence(phone, state)

Set the typing indicator for a chat without sending a message. state is 'typing' | 'paused'.

• Returns: Promise<void>

Conversations & takeover

msgkit.listConversations(), msgkit.getConversation(id), msgkit.getConversationMessages(id) — read a contact's conversation thread (inbound replies and outbound sends merged chronologically, each returning Conversation / ConversationMessage[]). msgkit.takeoverConversation(id, options?) / msgkit.resumeConversation(id, options?) flip state between 'bot' and 'human'; options is { actor?: string; reason?: string }.

msgkit.getMedia(messageId)

Downloads the raw bytes of an inbound image/video/audio/document message msgkit captured when it arrived.

• Returns: Promise<MediaFile> — { data: ArrayBuffer; contentType: string }
• Throws: MsgkitError with statusCode 404 if the message wasn't media, or if the download failed at receive time

Error Handling

The SDK throws typed errors for business failures — no need to parse HTTP status codes:

import { createClient, RateLimitError } from 'msgkit-client'

const msgkit = createClient('http://localhost:54321', 'msgkit_anon_xxx')

try {
  await msgkit.sendText('+212600000000', 'Hello world')
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`)
  }
}

| Error Class | When | |-------------|------| | RateLimitError | Exceeded the per-minute rate limit (HTTP 429) | | MsgkitError | Base class for all SDK errors |

Auto-Retry

Transient network errors (502, 503, 504, timeouts) are automatically retried with exponential backoff. Business errors (rate limit) are never retried.

Requirements

• Node.js ≥ 18 (uses native fetch)
• A running Msgkit instance

License

MIT — see LICENSE for details.