Skip to content
Get an API key

Get started

Your clients

One client per end customer, one key to drive them all. Your customers never create a Nodium account.

You publish software; each of your customers wants their own WhatsApp. Add each one as a client (/tenants): its own numbers, conversations and templates, isolated from the others. Your own company is the first client, My company; a direct business connects its number there. You drive every client with your account key.

Shell

# 1. Add one of your customers as a clientcurl https://nodium.io/api/v1/tenants \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Optique Martin", "externalId": "cust_1042", "locale": "fr" }'# 2. A hosted connect link, to send to that customercurl https://nodium.io/api/v1/tenants/cust_1042/connect-links \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "redirectUrl": "https://app.example.com/settings/whatsapp", "prefill": { "name": "Optique Martin", "website": "optique-martin.fr", "country": "FR", "category": "RETAIL" } }'# → data.url: send it. Back on your side:# https://app.example.com/settings/whatsapp?status=connected&channel_id=…# 3. Act for that client: same key, one headercurl https://nodium.io/api/v1/conversations \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Nodium-Tenant: cust_1042"

Clients

  • POST /tenants adds one. Pass your own externalId: it is unique in your account, so replaying the call answers 409 tenant_exists with the existing id instead of creating a duplicate.
  • Everywhere a client id is expected, your externalId works too.
  • GET /tenants, GET /tenants/{id}, PATCH /tenants/{id} (name, externalId, locale, time zone), DELETE /tenants/{id} to close it. Each one carries its WhatsApp state, its latest connect link and its activity this month.
  • The clients limit of your plan counts every client of the account except My company: 402 plan_limit beyond it. The free plan (Build) includes none, so adding a client — POST /tenants or a connect link for another client — needs Launch. A client itself costs nothing: your plan is priced on the WhatsApp numbers connected and the messages (see Authentication › Quota).
  • POST /tenants/{id}/connect-links returns a url to send to your customer. It opens a Nodium page with three steps: which app the number is on, a short Your business form with everything Meta asks for, then Meta's signup window, already filled from that form — coexistence with the WhatsApp Business app included. Meta's window does not open until the form is complete.
  • The link works once and expires after 7 days by default (expiresInDays, 30 at most). The address is shown only in that response.
  • The first step asks which app the number is on: the WhatsApp Business app they keep (coexistence), none (dedicated), or regular WhatsApp — which Meta refuses, so the page tells them to move the number to WhatsApp Business first. If you already know, pass mode and the question disappears. phoneNumber limits the link to one number, named on the page: any other one is refused and the link can be used again.
  • prefill fills the Your business form field by field: name, displayName (the name shown in WhatsApp), email, website (or a Facebook or Instagram page), address, country, category and description. Your customer only checks what you already know. Without name, the form proposes the tenant name: give the real business name if yours are internal ids.
  • A payment method at Meta is needed to message first (templates) and to reply beyond the 1,000 free service messages each number gets per month; without one, the number still receives and replies within that allowance. The page says so once connected, and Meta bills your customer directly.
  • When they finish, they land on your redirectUrl with status=connected&channel_id=…; if they give up, status=cancelled; if it failed and they go back, status=failed&code=… (the codes of channel.connect_failed). Confirm with GET /tenants/{id}/channels, or listen to the channel.connected webhook.
  • A pending link can be extended or pointed to another redirectUrl with PATCH /connect-links/{id}: the address you already sent keeps working.
  • PATCH /tenants/{id} with business fills the Your business form from your own records and keeps it for the next number; GET /tenants/{id} returns it, with business.complete once Meta's window can open right away.
  • GET /connect-links lists every link of your account (state: pending, used, expired; filter with state or client). The address itself is never returned again — only a hash is kept — so a lost link is replaced by a new one.
  • DELETE /connect-links/{id} revokes a link that has not been used yet: it stops working at once and shows as expired.

Acting for a client

  • Add Nodium-Tenant: <id or externalId> to any call with your account key. A client outside your account answers 404.
  • Or issue a key pinned to one client: POST /keys with clientId, shown once. It can never act on another client.
  • One webhook is enough: a subscription created without Nodium-Tenant (on your own company) receives the events of every client of your account. Every payload carries workspace_id, the client the event comes from. A subscription created with the header, or with a pinned key, receives that client's events only.
  • Each client has its own templates, deployed to its WhatsApp accounts (see Sending).

Meta's fees

Meta bills its message fees directly to each customer's WhatsApp Business account, with no markup from Nodium. Without a payment method there, the number still receives, and answers inside the 24-hour window within the 1,000 free service messages per number each month; any other send is refused by Meta (error 131042): the channel is flagged paymentMissing, and message.failed carries error_code, reason: "payment_missing" and a hint you can pass to your customer. The console also lists it under what needs your attention.