Skip to content
Get an API key

Get started

Get started

Nodium connects your backend to WhatsApp and Muse. From nothing to a first message sent and answered, in three calls.

Nodium is a gateway: it carries messages between WhatsApp (and Muse, Meta's assistant) and your backend. It never answers for you — your code decides every reply. Inbound messages reach you by webhook; you answer through the API.

  • Base address: https://nodium.io/api/v1. Every call is JSON over HTTPS, authenticated with one key: Authorization: Bearer nod_….
  • Answers come as { "data": … } or { "error": { "code", … } }. Branch on error.code, never on the text.
  • Limits: 600 calls per minute per client for a key that acts on every client of your account (6,000 per key at most); 600 per minute for a key pinned to one client. Reported in X-RateLimit-* headers.
  • Reference: every route, field and error code is in the Reference section, generated from the code. The OpenAPI document is at /docs/api/openapi.json, an index for agents at /docs/api/llms.txt.

Try it without a number

No number of your own, no Meta verification, no template to approve: the sandbox is a WhatsApp number shared by Nodium. Link your own phone to your account by sending it a code, then send and receive like on a real number — message.received included. Three calls, a few minutes.

Shell

# 1. Your sandbox: the shared number and your join codecurl https://nodium.io/api/v1/sandbox \ -H "Authorization: Bearer $NODIUM_KEY"# Open data.waLink on your phone (or send data.joinMessage, "join <code>", to# data.displayPhone): your phone is linked and the 24-hour window opens.# 2. Read the sandbox again: data.channelId is now setcurl https://nodium.io/api/v1/sandbox \ -H "Authorization: Bearer $NODIUM_KEY"# 3. Write to your phone in free text, on the sandbox channelcurl https://nodium.io/api/v1/messages \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "channelId": "<data.channelId>", "to": "<your phone, E.164>", "type": "text", "text": "Hello from Nodium", "idempotencyKey": "sandbox-hello-1" }'

Limits: only linked phones receive, only inside the 24-hour window, free text only (no templates), and a daily number of sends per account. The sandbox needs a key that sees every client of your account, and is open only when the server has enabled it (data.available). When you are ready, connect your own number (below) and send templates.

Before the first call

  • Create an account: it comes with a first client, My company, and an app. Nothing else is required before the first call.
  • Create an API key in the console, under Settings › API keys, or with POST /keys. It is shown once. In TypeScript, install the SDK: npm i @nodium.io/whatsapp, then new Nodium(process.env.NODIUM_KEY) (see TypeScript SDK); the nodium command of @nodium.io/cli replays your webhooks to your own machine (see Webhooks). From any other language, call the API directly: the OpenAPI document carries a code sample for every route.
  • To send and receive on your own number, connect one through Meta's signup window, from the hosted connect link. The number belongs to you or your customer; Nodium does not provide numbers. With coexistence, the WhatsApp Business app keeps working on the same number. Until then, the sandbox above is enough to try everything in free text.
  • Register a webhook address (console, or POST /webhooks) so Nodium can tell you when a customer writes.
  • Building for many customers? Read Your clients first: each customer is a client of your account and connects their own number from a hosted link.

Three calls, on your own number

Shell

# 1. Which numbers can I send from?curl https://nodium.io/api/v1/channels \ -H "Authorization: Bearer $NODIUM_KEY"# 2. Write first to a customer: on WhatsApp, an approved templatecurl https://nodium.io/api/v1/messages \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "channelId": "<channel id>", "to": "+33612345678", "type": "template", "templateName": "order_ready", "templateLanguage": "en", "variables": { "1": "Karim" }, "idempotencyKey": "order-1042-confirmation" }'# 3. The customer answers: you receive message.received on your webhook.# Reply in free text, within 24 hours:curl https://nodium.io/api/v1/messages \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "channelId": "<channel id>", "to": "+33612345678", "type": "text", "text": "Yes, it is ready.", "idempotencyKey": "order-1042-reply-1" }'

That is the whole loop: list your channels, write first with an approved template, receive the answer by webhook, reply in free text.

Where to look next

  • TypeScript SDK — @nodium.io/whatsapp and the nodium command: install, send, receive, Flows, errors.
  • Concepts — account, client, channel, conversation, contact, template, webhook: how they fit.
  • Authentication — the account key, roles, expiry, the client header, limits and quota.
  • Responses and errors — the data / error envelope, pagination.
  • The 24-hour window — the WhatsApp rule that decides what you may send.
  • Sending — idempotency keys, the queue, retries.
  • Webhooks — events, numbers, signatures, retries, ordering.
  • Flows — WhatsApp forms, static or backed by your own endpoint.
  • Coexistence — a number that keeps the WhatsApp Business app.
  • Running your numbers — statistics, media, contact export, business profile, connect links, search.
  • Muse (MCP) — publish your app as a hosted MCP server.
  • Your clients — one client per end customer, connected from a hosted link.