> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazzapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Install and use the official @wazzapi/wazzapi Node.js and TypeScript SDK for messages, devices, contacts, templates, and webhook verification

# Node.js SDK

The official Node.js and TypeScript SDK gives you a typed client for the public WazzAPI surface.

Use it to:

* send direct WhatsApp messages
* pair SDK usage with the public API for device inventory and sender selection
* manage contacts, groups, and templates
* verify signed WazzAPI webhook deliveries
* download and decrypt WhatsApp media payloads

<CardGroup cols={2}>
  <Card title="Package" icon="box" href="https://www.npmjs.com/package/@wazzapi/wazzapi">
    Install the published package from npm.
  </Card>

  <Card title="Source code" icon="github" href="https://github.com/wazzapihq/wazzapi-node">
    Browse the SDK repository, examples, and release history.
  </Card>
</CardGroup>

## Requirements

* Node.js `20`, `22`, or `24`
* a WazzAPI account
* a WazzAPI API key

If you plan to verify webhooks, also create a webhook secret in the dashboard.

<Warning>
  Do not use this SDK in browser-side code. Keep your WazzAPI credentials on the server only.
</Warning>

## Install

Choose the package manager that fits your stack:

```bash npm theme={null}
npm install @wazzapi/wazzapi
```

```bash bun theme={null}
bun add @wazzapi/wazzapi
```

## Configuration

The SDK uses `https://api.wazzapi.com` by default.

For most integrations, you only need:

* `WAZZAPI_API_KEY`

For webhook verification, also set:

* `WAZZAPI_WEBHOOK_SECRET`

```bash .env theme={null}
WAZZAPI_API_KEY=wz_live_your_api_key
WAZZAPI_WEBHOOK_SECRET=whsec_your_webhook_secret
```

## Quick start

### Send a message

```ts theme={null}
import { WazzapiClient } from "@wazzapi/wazzapi";

const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });

const response = await client.messages.send({
  phone_number: "+6281234567890",
  whatsapp_account_id: "your-whatsapp-account-id",
  content: "Hello from WazzAPI!",
});

console.log(response.message_id, response.status);
```

### List devices

```ts theme={null}
const response = await fetch("https://api.wazzapi.com/api/v1/devices", {
  headers: {
    Authorization: `Bearer ${process.env.WAZZAPI_API_KEY}`,
  },
});

const devices = await response.json();

console.log(devices.total);
console.log(devices.devices.map((device) => [device.id, device.name, device.status]));
```

### Verify incoming webhooks

Use `WebhookHandler` to validate the raw request body against the signature header before parsing JSON.

```ts theme={null}
import { WebhookHandler } from "@wazzapi/wazzapi";

const handler = new WebhookHandler(process.env.WAZZAPI_WEBHOOK_SECRET || "");
const webhook = handler.verifyAndParse(rawBody, request.headers);

console.log(webhook.event_type);
console.log(webhook.data);
```

WazzAPI signs webhook deliveries with:

* `X-Wazzapi-Signature`
* `X-Wazzapi-Event`
* `X-Wazzapi-Event-ID`

Supported event families include:

* message events: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`
* device events: `device.connected`, `device.disconnected`

## Handle API errors

When the API returns a non-success status, the SDK raises `WazzapiAPIError`.

```ts theme={null}
import { WazzapiAPIError, WazzapiClient } from "@wazzapi/wazzapi";

try {
  const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
  await client.messages.get("missing-message-id");
} catch (error) {
  if (error instanceof WazzapiAPIError) {
    console.error(error.statusCode);
    console.error(error.message);
    console.error(error.details);
  }
}
```

## Example scripts

The SDK repository includes ready-to-run examples:

* `examples/list-contacts.ts`
* `examples/send-message.ts`
* `examples/create-template.ts`
* `examples/preview-template.ts`
* `examples/verify-webhook.ts`
* `advanced-examples/download-media.ts`

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Create your API key and send your first live request.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore endpoints and payloads behind the SDK methods.
  </Card>
</CardGroup>