@nasaq/openwa

Headless TypeScript client for the OpenWA WhatsApp API Gateway.

Use it from any backend (Node, NestJS, Express, etc.). Build your own admin UI in Angular, React, plain HTML, or anything else — this package provides APIs only.

Install

From another NASAQ project:

npm install @nasaq/openwa

Local development (file link):

{
  "dependencies": {
    "@nasaq/openwa": "file:../openWA/packages/nasaq-openwa"
  }
}

Requires a running OpenWA service. See docs/NASAQ-LOCAL-SETUP.md.

Quick start

import { OpenWAClient, formatChatId } from '@nasaq/openwa';

const client = new OpenWAClient({
  baseUrl: process.env.OPENWA_BASE_URL!,
  apiKey: process.env.OPENWA_API_KEY!,
});

await client.health.check();

await client.messages.sendText({
  sessionId: process.env.OPENWA_SESSION_ID!,
  chatId: formatChatId('966500706258'),
  text: 'Hello from Pacioli',
});

Environment variables

| Variable | Description | |----------|-------------| | OPENWA_BASE_URL | OpenWA API base URL (e.g. http://localhost:2785) | | OPENWA_API_KEY | API key (X-API-Key header) | | OPENWA_SESSION_ID | WhatsApp session UUID |

Store secrets in your backend only. Never expose the API key in browser code.

Admin integration flow

Typical setup from your project's admin backend:

1. client.health.check() — verify OpenWA is reachable
2. client.health.validateApiKey() — verify credentials
3. client.sessions.create({ name: 'pacioli' }) — create session
4. client.sessions.start(session.id) — start engine
5. client.sessions.getQr(session.id) — return qrCode (base64) to your admin UI
6. client.setup.waitUntilReady(session.id) — poll until linked
7. client.setup.runIntegrationCheck({ sessionId, testPhone, testMessage }) — verify end-to-end

Your admin UI handles QR display and status; this package handles OpenWA API calls.

API reference

OpenWAClient

| Namespace | Methods | |-----------|---------| | health | check(), validateApiKey() | | sessions | list(), get(), create(), start(), stop(), delete(), getQr() | | messages | sendText({ sessionId, chatId, text }) | | setup | waitUntilReady(), runIntegrationCheck(), isSessionReady() |

Helpers

• formatChatId('966500706258') → [email protected]
• normalizePhone('+966 500 706 258') → 966500706258
• isSessionReady(status) — true for ready or connected

Errors

Failed API calls throw OpenWAError with status, optional code, and message.

Manual integration check

cd packages/nasaq-openwa
npm run build

OPENWA_BASE_URL=http://localhost:2785 \
OPENWA_API_KEY=dev-admin-key \
OPENWA_SESSION_ID=your-session-id \
node examples/check-integration.mjs

Build and test

npm run build --workspace=@nasaq/openwa
npm run test --workspace=@nasaq/openwa

From repo root:

npm run sdk:build
npm run sdk:test

License

MIT