Skip to content
Get an API key

Get started

Get started

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

Nodium is a gateway: it carries messages between WhatsApp 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.

Before the first call

  • Create an account: it comes with a first client, My company. 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 checks your setup and replays your webhooks to your own machine (see CLI). 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.
  • 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.
  • CLI — the nodium command: your setup, numbers, templates and webhooks from the terminal, and events replayed locally.
  • Concepts — account, client, channel, conversation, contact, template, webhook: how they fit.
  • Authentication — the account key, 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.
  • Your clients — one client per end customer, connected from a hosted link.