TypeScript SDK

The official Keebai SDK for Node.js, TypeScript, and modern runtimes. Saves you from writing your own HTTP layer against Meta Graph API or api.keebai.com/v1.

Pending migration. The published SDK still targets the per-type routes (/v1/messages/text, /v1/messages/image, …) that were replaced by the single POST /v1/messages. Its keebai mode will fail against the current API until a new version ships; meta mode, which talks straight to Meta Cloud API, is unaffected. Call the REST endpoint directly in the meantime.

import { WhatsAppClient } from "@keebai/sdk";

const wa = new WhatsAppClient({
  apiKey: process.env.KEEBAI_API_KEY!,        // kbai_pk_<hex64>
  phoneNumberId: process.env.KEEBAI_PHONE_NUMBER_ID!,
});

await wa.messages.sendText({
  to: "+15551234567",
  body: "Hello from Keebai",
});

That’s it.

Why use it

One client, two modes

Pass apiKey and it talks to Keebai with persistence, dashboards, broadcasts, and normalized webhooks. Pass accessToken and it goes straight to Meta Graph API. Same method surface in both modes.

Full WhatsApp coverage

Text, media (image, video, audio, document, sticker), location, contact cards, reactions, mark-read, interactive (buttons, list, CTA URL, catalog), templates, and broadcasts.

Strict TypeScript

Fully typed: inputs, responses, errors. Autocomplete in VS Code, Cursor, or any LSP-aware IDE. Dual ESM + CJS build with .d.ts.

Retries and timeouts

Automatic exponential backoff on 429, 5xx, and network errors. Configurable timeout. Normalizes Keebai and Meta errors into the same class.

Installation

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

Requires Node.js 20+ (uses global fetch, FormData, and Blob). Also works on edge runtimes (Vercel Edge, Cloudflare Workers, Deno, Bun) and modern browsers.

Configuration

Set credentials via environment variables:

export KEEBAI_API_KEY=kbai_pk_<hex64>        # from app.keebai.com → System Settings → API Keys
export KEEBAI_PHONE_NUMBER_ID=<numeric>       # phone_number_id of your WhatsApp Cloud API channel
export KEEBAI_BASE_URL=https://api.keebai.com/v1   # optional; default

Instantiate the client:

import { WhatsAppClient } from "@keebai/sdk";

const wa = new WhatsAppClient({
  apiKey: process.env.KEEBAI_API_KEY!,
  phoneNumberId: process.env.KEEBAI_PHONE_NUMBER_ID!,
});

The two modes

Mode	Credential	Backend	When
`keebai` (default)	`apiKey: kbai_pk_...`	`https://api.keebai.com/v1`	You’re on the Keebai platform. Persistence, multi-tenant, broadcasts, webhooks, dashboards.
`meta`	`accessToken: EAA...`	`https://graph.facebook.com/v21.0`	You have your own WhatsApp Business Account and want to go straight to Meta.

The client infers the mode from the credential. Same method names, same return types, same error model — only the transport changes.

// Direct to Meta
const wa = new WhatsAppClient({
  accessToken: process.env.META_ACCESS_TOKEN!,
  phoneNumberId: process.env.META_PHONE_NUMBER_ID!,
});

Trade-off details in Direct Meta mode.

API surface

`client.messages.*`

Method	What it does
`sendText`	Free-form text inside the 24h window.
`sendImage`	JPG/PNG by URL or `media_id`. Optional caption.
`sendVideo`	MP4 with optional caption.
`sendAudio`	Audio. `voice: true` for PTT (Opus in OGG).
`sendDocument`	PDF/DOCX/etc. with filename and caption.
`sendSticker`	Static or animated WebP.
`sendLocation`	Map pin with optional name and address.
`sendContacts`	One or more vCards.
`sendReaction`	Emoji on a previous message.
`markRead`	Mark as read, with optional typing indicator.
`sendInteractiveButtons`	Up to 3 reply buttons.
`sendInteractiveList`	Scrollable list with sections.
`sendInteractiveCtaUrl`	Single button with an external URL.
`sendInteractiveCatalogMessage`	Catalog message (Commerce).
`sendTemplate`	Approved template with named variables.
`sendBulk`	Mass broadcast (Keebai mode).
`getBulkStatus`	Status of a previous broadcast (Keebai mode).
`sendRaw`	Escape hatch — raw Graph API body.

`client.media.*`

Method	What it does
`upload`	Upload a file. Returns a reusable `media_id`.
`get`	Metadata (mime, size, sha256, signed URL).
`delete`	Delete an uploaded media asset.
`download`	Fetch the binary (`as: 'blob' \| 'arraybuffer'`).

`client.templates.` (Keebai mode)*

Method	What it does
`list`	List approved templates.
`create`	Create and submit to Meta for approval.
`update`	Edit components or category.

Examples

Send an image with a caption

await wa.messages.sendImage({
  to: "+15551234567",
  image: {
    link: "https://cdn.example.com/banner.png",
    caption: "New collection",
  },
});

Template with named variables

await wa.messages.sendTemplate({
  to: "+15551234567",
  templateName: "order_confirmation",
  language: "en_US",
  variables: {
    name: "Alex",
    order: "ORD-1234",
    amount: "$15,000",
  },
});

Interactive buttons

await wa.messages.sendInteractiveButtons({
  to: "+15551234567",
  bodyText: "Confirm your order?",
  buttons: [
    { id: "confirm", title: "Confirm" },
    { id: "cancel", title: "Cancel" },
  ],
});

Upload media once, send N times

import { readFile } from "node:fs/promises";

const buffer = await readFile("logo.png");
const file = new Blob([buffer], { type: "image/png" });

const { id: mediaId } = await wa.media.upload({
  file,
  fileName: "logo.png",
  type: "image/png",
});

for (const phone of recipients) {
  await wa.messages.sendImage({
    to: phone,
    image: { id: mediaId, caption: "Keebai logo" },
  });
}

Mark as read + typing

await wa.messages.markRead({
  messageId: "wamid.HBgL...",
  typingIndicator: "text",
});

Mass broadcast

const { broadcastId } = await wa.messages.sendBulk({
  templateName: "march_promo",
  language: "en_US",
  campaignName: "March 2026",
  recipients: [
    { to: "+15551234567", variables: { name: "Alex" } },
    { to: "+15557654321", variables: { name: "Sam" } },
  ],
});

const status = await wa.messages.getBulkStatus(broadcastId);
console.log(`${status.sent}/${status.total} sent`);

Error handling

import {
  WhatsAppApiError,
  WhatsAppValidationError,
  WhatsAppTimeoutError,
} from "@keebai/sdk";

try {
  await wa.messages.sendText({ to: "+15551234567", body: "hello" });
} catch (err) {
  if (err instanceof WhatsAppApiError) {
    console.log(err.status, err.code, err.message);
  }
}

Common codes:

Code	Status	Cause
`UNAUTHORIZED`	401	Token revoked or invalid.
`FORBIDDEN`	403	Token doesn’t have the required scope.
`CHANNEL_NOT_FOUND`	404	`phoneNumberId` unknown in your company.
`invalid_phone`	422	`to` is not in E.164 format.
`MEDIA_REFERENCE_REQUIRED`	400	Media is missing both `link` and `media_id`.
`THROTTLED`	429	Hit the rate limit (the SDK retries on its own).

429s, 5xx, and network errors retry automatically with exponential backoff. Configurable:

new WhatsAppClient({
  apiKey: "kbai_pk_...",
  phoneNumberId: "100000000000001",
  timeoutMs: 30_000,
  retries: 2,                              // default
});

Direct Meta mode

When you’d rather go straight to Meta without the platform:

const wa = new WhatsAppClient({
  accessToken: process.env.META_ACCESS_TOKEN!,
  phoneNumberId: process.env.META_PHONE_NUMBER_ID!,
});

Concern	`keebai` mode	`meta` mode
Auth	PAT (`kbai_pk_...`) from app.keebai.com	Access token (`EAA...`) from developers.facebook.com
Persistence	Yes — conversations, messages, contacts	No — Meta doesn’t store history
Normalized webhooks	Yes — `{ event, data, timestamp }` envelope with HMAC signature	No — raw Meta envelope
Broadcasts (`sendBulk`)	Yes	Not available
Templates CRUD	Yes	Not in this SDK; use the Business Management API
Dashboard	Yes	No
Multi-tenant	One PAT, multiple channels	One token per WABA
Send messages	Full coverage	Full coverage

Helpers

import { buildTemplateSendPayload, normalizePhone } from "@keebai/sdk";

const template = buildTemplateSendPayload({
  name: "welcome",
  language: "en_US",
  body: [{ type: "text", text: "Alex", parameterName: "name" }],
  buttons: [{ subType: "quick_reply", index: 0, payload: "GO" }],
});

const phone = normalizePhone("(555) 123-4567"); // "+15551234567"

Resources

GitHub repo

Source code, issues, and PRs. MIT.

npm: @keebai/sdk

Latest version, changelog, install stats.

Agent Skills

The integrate-keebai-whatsapp skill for AI agents, built on this SDK.

REST API

If you’d rather call the API directly without the SDK.

Get started

Authentication

MCP

SDK

CLI

Agent Skills

Limits

TypeScript SDK

Why use it

One client, two modes

Full WhatsApp coverage

Strict TypeScript

Retries and timeouts

Installation

Configuration

The two modes

API surface

`client.messages.*`

`client.media.*`

`client.templates.` (Keebai mode)*

Examples

Send an image with a caption

Template with named variables

Interactive buttons

Upload media once, send N times

Mark as read + typing

Mass broadcast

Error handling

Direct Meta mode

Helpers

Resources

GitHub repo

npm: @keebai/sdk

Agent Skills

REST API

​Why use it

One client, two modes

Full WhatsApp coverage

Strict TypeScript

Retries and timeouts

​Installation

​Configuration

​The two modes

​API surface

​client.messages.*

​client.media.*

​client.templates.* (Keebai mode)

​Examples

​Send an image with a caption

​Template with named variables

​Interactive buttons

​Upload media once, send N times

​Mark as read + typing

​Mass broadcast

​Error handling

​Direct Meta mode

​Helpers

​Resources

GitHub repo

npm: @keebai/sdk

Agent Skills

REST API

Why use it

Installation

Configuration

The two modes

API surface

`client.messages.*`

`client.media.*`

`client.templates.` (Keebai mode)*

Examples

Send an image with a caption

Template with named variables

Interactive buttons

Upload media once, send N times

Mark as read + typing

Mass broadcast

Error handling

Direct Meta mode

Helpers

Resources