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.
# 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 /tenantsadds one. Pass your ownexternalId: it is unique in your account, so replaying the call answers409 tenant_existswith the existing id instead of creating a duplicate.- Everywhere a client id is expected, your
externalIdworks 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
clientslimit of your plan counts every client of the account except My company:402 plan_limitbeyond it. The free plan (Build) includes none, so adding a client —POST /tenantsor 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).
The hosted connect link
POST /tenants/{id}/connect-linksreturns aurlto 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, passmodeand the question disappears.phoneNumberlimits the link to one number, named on the page: any other one is refused and the link can be used again. prefillfills the Your business form field by field:name,displayName(the name shown in WhatsApp),email,website(or a Facebook or Instagram page),address,country,categoryanddescription. Your customer only checks what you already know. Withoutname, 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
redirectUrlwithstatus=connected&channel_id=…; if they give up,status=cancelled; if it failed and they go back,status=failed&code=…(the codes ofchannel.connect_failed). Confirm withGET /tenants/{id}/channels, or listen to thechannel.connectedwebhook. - A pending link can be extended or pointed to another
redirectUrlwithPATCH /connect-links/{id}: the address you already sent keeps working. PATCH /tenants/{id}withbusinessfills the Your business form from your own records and keeps it for the next number;GET /tenants/{id}returns it, withbusiness.completeonce Meta's window can open right away.GET /connect-linkslists every link of your account (state:pending,used,expired; filter withstateorclient). 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 asexpired.
Acting for a client
- Add
Nodium-Tenant: <id or externalId>to any call with your account key. A client outside your account answers404. - Or issue a key pinned to one client:
POST /keyswithclientId, 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 carriesworkspace_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.