Get started

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.

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 is billed for a month once it is active (a message sent or received, or a tool call served).

The hosted connect link

• POST /tenants/{id}/connect-links returns a url to send to your customer. It opens a Nodium page where they connect their number in Meta's signup window — coexistence with the WhatsApp Business app included — and are invited to add a payment method at Meta.
• The link works once and expires after 7 days by default (expiresInDays, 30 at most). The address is shown only in that response.
• When they finish, they land on your redirectUrl with status=connected&channel_id=…, or status=cancelled. Confirm with GET /tenants/{id}/channels, or listen to the channel.connected webhook.
• 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 (role admin, agent or member), 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.
• Templates are written once for the account and deployed to each client's WhatsApp account (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 free inside the 24-hour window, but a paid 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.