Skip to content
Get an API key

Get started

Concepts

Seven words explain the whole API.

  • Account — you: the publisher or company that pays Nodium. Your plan, your API keys and the templates you write once belong to the account.
  • Client (also called a tenant or workspace) — one of your customers, isolated from the others: its own numbers, conversations, contacts, webhooks and Flows. My company is your own, the first one. externalId is your own identifier for a client, and works wherever a client id is expected.
  • Channel — a WhatsApp number connected to a client. GET /channels gives you the channelId every first message needs.
  • Contact — a person who wrote to, or was written to from, a channel. Identified by phone number; it carries the marketing consent (optInAt, optOutAt).
  • Conversation — one contact on one channel: the thread, with its 24-hour window and the delivery receipts of each message.
  • Template — a message pre-approved by Meta. It is written once for your account and deployed to each client's WhatsApp account; it is the only way to write first, or to write after the window closed.
  • Webhook — your subscription to events (message.received, message.failed…). One on My company receives the events of every client, each payload naming its client in workspace_id.

How they fit

Text

account (plan, API keys, templates) └─ client (My company, Optique Martin, …) ← header Nodium-Tenant ├─ channel a WhatsApp number │ └─ conversation one contact, 24-hour window │ └─ message in / out, status ├─ contact ├─ webhook subscription └─ Flows, broadcasts, media

Which client does a call act on?

  • A key belongs to the account. Each call acts on one client: the one the key is pinned to, otherwise the one named by the Nodium-Tenant header, otherwise My company.
  • Something that belongs to another client, or to another account, answers 404, never 403.
  • What you define once for the account (templates, keys, your plan) is read across all clients. What a client operates (numbers, messages, webhooks, Flows) is read for the client the call acts on.

A message's life

  • In: WhatsApp → Nodium → message.received on your webhook → your code decides.
  • Out: your code → POST /messages (a channel and a person, never a conversation id) → WhatsApp. Its status moves queued → sent → delivered → read, each step a webhook, or failed with the reason.
  • Nodium never sends anything you did not ask for, and never decides what to say.