360dialog-whatsapp-sdk

360dialog-whatsapp-sdk

A fully-typed TypeScript SDK for the 360dialog WhatsApp Business Platform. It covers every API documented in the 360dialog client documentation — the Messaging API (messages, marketing messages, templates, flows, media, groups, calling, profile, business username, contact book, block users, payments, business compliance, conversational components, encryption, RCS, health) and the Meta Business Agent API (onboarding, knowledge base, connectors, operate) — plus the sandbox. Webhooks and Inbox are intentionally out of scope (see COVERAGE.md for the endpoint-by-endpoint matrix).

• Built for Bun and Node.js ≥ 18 (ESM), transport via axios.
• Types are generated from the OpenAPI fragments published in the 360dialog docs (openapi/*.json, refreshable with one command) and enriched with hand-written payload types for every documented message type.
• Every documented operation is exercised by the test suite (bun test), which fails if an endpoint goes uncovered.

Install

bun add 360dialog-whatsapp-sdk
# or: npm install 360dialog-whatsapp-sdk

Quick start

import { Dialog360Client } from "360dialog-whatsapp-sdk";

const client = new Dialog360Client({ apiKey: process.env.D360_API_KEY! });

// Free-form text
await client.messages.sendText("4915112345678", "Hello from 360dialog 👋");

// Template
await client.messages.sendTemplate("4915112345678", {
  name: "order_update",
  language: { code: "en_US" },
  components: [{ type: "body", parameters: [{ type: "text", text: "#1234" }] }],
});

// Interactive buttons
await client.messages.sendInteractive("4915112345678", {
  type: "button",
  body: { text: "Confirm your appointment?" },
  action: {
    buttons: [
      { type: "reply", reply: { id: "yes", title: "Yes" } },
      { type: "reply", reply: { id: "no", title: "No" } },
    ],
  },
});

// Any documented payload (fully typed – see `OutboundMessage`)
await client.messages.send({
  messaging_product: "whatsapp",
  to: "4915112345678",
  type: "location",
  location: { latitude: 52.52, longitude: 13.405, name: "Berlin" },
});

Client options

const client = new Dialog360Client({
  apiKey: "…",                       // D360-API-KEY of the channel (or env WA_360DIALOG_API_KEY)
  baseUrl: "https://waba-v2.360dialog.io", // default (or env WA_360DIALOG_API_URL)
  sandbox: false,                    // true → https://waba-sandbox.360dialog.io
  timeoutMs: 30_000,                 // per-request timeout
  headers: { "X-Trace": "abc" },     // extra headers on every request
  axios: myAxiosInstance,            // bring your own axios (proxies, interceptors, retries)
  userAgent: null,                   // customise / disable the User-Agent header
  businessAgent: { apiVersion: "2.0.0" }, // X-API-Version for the Meta Business Agent API
});

Every method accepts an optional trailing CallOptions argument: { signal?: AbortSignal; timeoutMs?: number; headers?: Record<string, string> }.

Environment variables

Instead of passing apiKey/baseUrl, set them in the environment (see .env.example; Bun loads .env automatically, on Node use node --env-file=.env):

WA_360DIALOG_API_KEY=your-channel-api-key
WA_360DIALOG_API_URL=            # optional – empty = production, or https://waba-sandbox.360dialog.io

const client = Dialog360Client.fromEnv();      // or: new Dialog360Client() / createClient()
const sandbox = Dialog360Client.fromEnv({ sandbox: true }); // overrides always win

Explicit options take precedence over the environment. bun run smoke performs a live GET /health_status with those credentials (optionally sending a text: bun run smoke <phone> "hi").

Sandbox

const sandbox = new Dialog360Client({ apiKey: SANDBOX_KEY, sandbox: true });
await sandbox.sandbox.sendMessage({
  messaging_product: "whatsapp",
  to: "<YOUR_PHONE_NUMBER>",
  type: "text",
  text: { body: "Hello world" },
});

Resources

Examples

// Templates
const { data: templates } = await client.templates.list({ limit: 50 });
await client.templates.create({
  name: "welcome",
  category: "UTILITY",
  language: "en_US",
  components: [{ type: "BODY", text: "Welcome {{1}}!", example: { body_text: [["Ada"]] } }],
});

// Media
const { id } = await client.media.upload({ file: await Bun.file("./photo.jpg").arrayBuffer(), contentType: "image/jpeg", filename: "photo.jpg" });
await client.messages.sendImage("4915112345678", { id, caption: "📸" });
const { url } = await client.media.get(id!);
const { data: bytes, contentType } = await client.media.download(url!);

// Flows
const flow = await client.flows.create({ name: "Lead form", categories: ["LEAD_GENERATION"] });
await client.flows.uploadFlowJson(flow.id!, { file: { version: "7.0", screens: [] } });
await client.flows.publish(flow.id!);

// Groups
const group = await client.groups.create({ subject: "VIP customers" });
const { invite_link } = await client.groups.getInviteLink(group.id!);

// Meta Business Agent
await client.businessAgent.onboarding.createOnboardingSession("whatsapp");
await client.businessAgent.faq.create({ question: "Opening hours?", answer: "9–5, Mon–Fri." });
const eligibility = await client.businessAgent.onboarding.getEligibility();

Error handling

import { Dialog360ApiError, Dialog360NetworkError, Dialog360TimeoutError } from "360dialog-whatsapp-sdk";

try {
  await client.messages.sendText("…", "…");
} catch (err) {
  if (err instanceof Dialog360ApiError) {
    err.status;      // HTTP status
    err.code;        // Meta/WhatsApp error code (e.g. 131047)
    err.details;     // Meta Graph-style { message, type, code, error_data, fbtrace_id }
    err.problem;     // RFC 7807 details (Meta Business Agent API)
    err.body;        // raw response body
    err.isRateLimited;
  } else if (err instanceof Dialog360TimeoutError) {
    // retry…
  } else if (err instanceof Dialog360NetworkError) {
    // DNS / connection problem
  }
}

Types

• Hand-written payload types for POST /messages: OutboundMessage and friends (TextMessageRequest, InteractiveContent, TemplateContent, Contact, …) — everything documented under Message Types, Interactive, Payments, Calling, Groups and Typing Indicators.
• Generated types, namespaced per resource, e.g. Templates.MessageTemplate, Flows.CreateFlowRequest, Groups.GetGroupInfoResponse, Rcs.RcsMessageRequest, BusinessAgent.Faq.BizAIOmniChannelKnowledgeFAQRequest.
• messagingOperations / businessAgentOperations: registry of every documented operation (operationId → { method, path, … }).

Keeping up with the docs

bun run generate          # re-fetch llms.txt + API reference pages → openapi/*.json → src/generated/**
bun run typecheck         # tsc
bun test                  # unit tests + coverage test (fails if an operation is not covered)
bun run coverage:report   # regenerate COVERAGE.md
bun run build             # dist/ (ESM bundle + .d.ts)

If 360dialog documents a new endpoint, bun test will fail on the coverage suite until a method (and a test/coverage/* entry) is added for it.

License

GPL-3.0-only. See LICENSE.