Channels

14 endpoints in this family.

List the channels

GET/api/v1/channels

Returns every WhatsApp number the client you act on can speak from, with the identifier you need everywhere else. Start here: opening a conversation requires a channelId, and there is no other way to obtain one.

A channel that is switched off still appears, with isActive: false. Nothing is sent or received on it until someone switches it back on in Nodium. paymentMissing: true means Meta refused a paid message because the client's WhatsApp account has no payment method (error 131042): the client adds one in WhatsApp Manager; replies within 24 hours of the customer's last message still go out.

With scope=account (a key that sees every client), the numbers of all your clients, each with its client, quality, sending tier and whether it keeps the WhatsApp Business app (coexistence).

Query parameters

scopestring
account for the numbers of every client of your account.
account

Response

The channels, each with its id, type, public identity, and whether it is active.

data.itemsChannel[]
The channels.

curl https://nodium.io/api/v1/channels \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "items": [ {} ] }}

Create a test channel

POST/api/v1/channels

Creates the workspace's test channel: a channel wired to no provider, so that conversations and templates have something to attach to while you build. Nothing is sent or received on it — sends are written to the server log. One per workspace. A real WhatsApp number is connected through Meta's signup window, in Nodium or through a hosted connect link (POST /tenants/{id}/connect-links).

Response

The test channel.

data.channelobject
The channel: id, type, name, identity, provider (log), isTest (true), isActive.
data.connectedboolean
Always false: no provider is wired.

Refusals

409conflictThe workspace already has its test channel.

curl -X POST https://nodium.io/api/v1/channels \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "channel": {}, "connected": true }}

Delete a channel

DEL/api/v1/channels/{id}

Deletes a channel and its encrypted credentials. A channel that carries conversations cannot be deleted (409): switch it off instead with PATCH /channels/{id} — nothing is lost that way. A number connected through Meta's signup window is also disconnected at Meta: a dedicated number is unregistered, and Nodium leaves the WhatsApp account when no other number of it is in use. The number can then be connected elsewhere. If Meta refuses a step the channel is deleted anyway and providerDisconnect is failed.

Path parameters

idstring
The channel id.

Response

Confirmation that it is gone.

data.deletedboolean
Always true.
data.namestring
The name of the deleted channel.
data.providerDisconnectstring
done, failed (Meta refused a step; Nodium is alerted), or not_applicable (a test channel, or a number Nodium does not disconnect at Meta).

Refusals

409conflictThe channel carries conversations: switch it off instead.

curl -X DELETE https://nodium.io/api/v1/channels/<id> \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "deleted": true, "name": "…", "providerDisconnect": "…" }}

Get a channel

GET/api/v1/channels/{id}

Returns one channel with its state, its quality rating and messaging tier at the provider, and the result of the last health check (POST /channels/{id}/check), which is null until a check has run.

Path parameters

idstring
The channel id.

Response

The channel and its last health check.

data.channelobject
The channel: id, type, name, identity, isActive, qualityRating, messagingLimit, displayPhone, coexistence, createdAt and health (checkedAt, ok, status, verifiedName, nameStatus, throughputLevel, message).

curl https://nodium.io/api/v1/channels/<id> \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "channel": {} }}

Switch a channel on or off, or rename it

PATCH/api/v1/channels/{id}

A channel switched off keeps its credentials and history; Nodium stops processing its messages without stopping anything at the provider. Send isActive, name, or both.

Path parameters

idstring
The channel id.

Body

isActiveboolean
On or off.
namestring
A new name, 2 to 80 characters.

Response

The channel as it now is.

data.channelobject
The channel: id, name, isActive.
data.noticestring
A warning when the channel is on but cannot send yet, otherwise null.

Refusals

402plan_limitSwitching the number back on would exceed the numbers your plan includes.
409conflictThe number was disconnected, or Meta cut it off: it cannot be switched back on here.

curl -X PATCH https://nodium.io/api/v1/channels/<id> \  -H "Authorization: Bearer $NODIUM_KEY" \  -H "Content-Type: application/json" \  -d '{    "isActive": true,    "name": "…"  }'

Response

200 OK

{ "data": { "channel": {}, "notice": "…" }}

Check a WhatsApp number

POST/api/v1/channels/{id}/check

Asks Meta about the number behind the channel and records its quality rating and messaging tier. A refusal by Meta is an answer, not an error: ok: false with a reason.

Path parameters

idstring
The channel id.

Response

Whether the number answers, and its quality rating.

data.okboolean
Whether Meta knows and serves the number.
data.reasonstring
When ok is false: gateway_refused or number_not_found.
data.numberobject
When ok is true: displayPhone, status (Meta's state of the number, null when Meta did not say), canSendMessage, problems, qualityRating, messagingLimitTier, verifiedName, nameStatus, throughputLevel.
data.messagestring
A sentence for a human.

curl -X POST https://nodium.io/api/v1/channels/<id>/check \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "ok": true, "reason": "…", "number": {}, "message": "…" }}

Diagnose a WhatsApp number

POST/api/v1/channels/{id}/diagnostic

Finds out why a number does not receive or send: it checks the client and the number switch, our connection to WhatsApp, what WhatsApp says about the number, its business account and its payment method, whether Nodium receives the number's messages, and whether anything arrived recently. Meta is asked live, so the call takes a few seconds. Each check says what is wrong, who can fix it (you, nodium, meta when WhatsApp is reviewing, or none) and what to do. When actor is nodium, there is nothing to fix on your side: contact support. The call only reads: it records nothing (use the check route to refresh the quality rating). A refusal by Meta is a finding, not an error. Limited to 6 calls per minute per number.

Path parameters

idstring
The channel id.

Response

The checks of the number, each with its status and what to do.

data.atstring
When the diagnosis was made (ISO 8601).
data.verdictstring
The worst status among the checks.
okwarnfail
data.checksobject[]
The checks, from the client to WhatsApp.
Show fields
- checkstring
  What is checked.
  clientconnectionnumberhealthaccountpaymentreceptioninbound
- okboolean
  False when the check found a problem (warn or fail).
- statusstring
  skip when the check does not apply to this number or could not be made.
  okwarnfailskip
- codestring
  A stable code for the finding, such as number_quality_red. Test this, not the message.
- messagestring
  What was found, in a sentence.
- actionstring
  What to do. null when there is nothing to do.
- actorstring
  Who can fix it.
  younodiummetanone

Refusals

404not_foundNo such number in this client, or not one this key can read.
429rate_limitedMore than 6 diagnoses in a minute for this number. Wait for `Retry-After` seconds.

curl -X POST https://nodium.io/api/v1/channels/<id>/diagnostic \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{  "data": {    "at": "…",    "verdict": "ok",    "checks": [      {        "check": "client",        "ok": true,        "status": "ok",        "code": "…",        "message": "…",        "action": "…",        "actor": "you"      }    ]  }}

Get the display name of a WhatsApp number

GET/api/v1/channels/{id}/display-name

The name people see for the number, with Meta's review of it, and the name requested with POST /channels/{id}/display-name while Meta reviews it. Read from Meta on every call.

Path parameters

idstring
The channel id.

Response

The display name in use and the one requested.

data.displayNameobject
The display name.
Show fields
- verifiedNamestring
  The name in use, or null.
- nameStatusstring
  Meta's review of the name in use: APPROVED, DECLINED, PENDING_REVIEW… or null.
- requestedNamestring
  The name requested and not in use yet, or null.
- requestedStatusstring
  Meta's review of the requested name, or null.

Refusals

502upstream_errorMeta refused or did not answer.

curl https://nodium.io/api/v1/channels/<id>/display-name \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{  "data": {    "displayName": {      "verifiedName": "…",      "nameStatus": "…",      "requestedName": "…",      "requestedStatus": "…"    }  }}

Request a new display name

POST/api/v1/channels/{id}/display-name

Asks Meta to change the name people see for the number. Meta reviews it, usually within 48 hours; follow it with GET /channels/{id}/display-name. Meta allows 10 requests per number every 30 days. An Official Business Account (green tick) changes its name through Meta support only.

Path parameters

idstring
The channel id.

Body

namestringrequired
The new display name, 3 to 256 characters. It must follow Meta's display name guidelines.

Response

The display name, with the request waiting for Meta's review.

data.displayNameobject
As in GET /channels/{id}/display-name.

Refusals

422invalid_requestThe name is missing, too short or too long.
502upstream_errorMeta refused (guidelines, too many requests) or did not answer.

curl -X POST https://nodium.io/api/v1/channels/<id>/display-name \  -H "Authorization: Bearer $NODIUM_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "…"  }'

Response

200 OK

{ "data": { "displayName": {} }}

Get the profile of a WhatsApp number

GET/api/v1/channels/{id}/profile

Returns what people see when they open the business profile of the number: description, address, email, websites and business category. Read from Meta on every call.

Path parameters

idstring
The channel id.

Response

The business profile of the number.

data.profileobject
about, description, address, email, websites (two at most), vertical and pictureUrl. Empty string when a field is not set.

Refusals

502upstream_errorMeta refused or did not answer.

curl https://nodium.io/api/v1/channels/<id>/profile \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "profile": {} }}

Change the profile of a WhatsApp number

PATCH/api/v1/channels/{id}/profile

Changes the fields you send and leaves the others alone. websites is replaced as a whole (two at most, starting with http:// or https://). An empty vertical clears the category.

Path parameters

idstring
The channel id.

Body

aboutstring
The "Info" line, 1 to 139 characters.
descriptionstring
Up to 512 characters.
addressstring
Up to 256 characters.
emailstring
An email address, up to 128 characters; empty removes it.
websitesstring[]
Up to two addresses starting with http:// or https://.
verticalstring
The business category; empty clears it.
ALCOHOLAPPARELAUTOBEAUTYEDUENTERTAINEVENT_PLANFINANCEGROCERYGOVTHEALTHHOTELNONPROFITNOT_A_BIZOTC_DRUGSOTHERPROF_SERVICESRESTAURANTRETAILTRAVEL

Response

Confirmation that Meta accepted the change.

data.updatedboolean
Always true.

Refusals

422invalid_requestA field is outside Meta's limits, or nothing was sent.
502upstream_errorMeta refused or did not answer.

curl -X PATCH https://nodium.io/api/v1/channels/<id>/profile \  -H "Authorization: Bearer $NODIUM_KEY" \  -H "Content-Type: application/json" \  -d '{    "about": "…",    "description": "…"  }'

Response

200 OK

{ "data": { "updated": true }}

Remove the username of a WhatsApp number

DEL/api/v1/channels/{id}/username

Removes the WhatsApp username of the number. People can no longer reach it as @username.

Path parameters

idstring
The channel id.

Response

Confirmation that Meta removed the username.

data.deletedboolean
Always true.

Refusals

502upstream_errorMeta refused or did not answer.

curl -X DELETE https://nodium.io/api/v1/channels/<id>/username \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "deleted": true }}

Get the username of a WhatsApp number

GET/api/v1/channels/{id}/username

The WhatsApp username of the number (people can reach it as @username without its phone number), and the usernames Meta reserved for it, which are more likely to be accepted. Read from Meta on every call.

Path parameters

idstring
The channel id.

Response

The username and the reserved suggestions.

data.usernamestring
The username, without @, or null.
data.statusstring
approved (visible to people) or reserved (held for the number, not visible yet); null without a username.
data.suggestionsstring[]
Usernames Meta reserved for this number.

Refusals

502upstream_errorMeta refused or did not answer.

curl https://nodium.io/api/v1/channels/<id>/username \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "username": "…", "status": "…", "suggestions": [ "…" ] }}

Set the username of a WhatsApp number

PUT/api/v1/channels/{id}/username

Claims or changes the WhatsApp username of the number. A username has 3 to 35 characters: letters a-z without accents, digits, . and _, at least one letter; it does not start or end with ., has no two . in a row, does not start with www. and does not end with a domain such as .com. Case is ignored. The answer is immediate: approved (visible to people) or reserved (held for the number, not visible yet).

Path parameters

idstring
The channel id.

Body

usernamestringrequired
The username, without @.
transferboolean
true takes the username from another number of the same Meta business portfolio. Default false.

Response

The username and its status.

data.usernamestring
The username.
data.statusstring
approved or reserved.

Refusals

409username_unavailableMeta refused the username: taken, not allowed, or the account is not eligible yet. `detail` gives Meta's reason.
409username_transfer_requiredAnother number of the same portfolio has it. Send again with `transfer: true`.
422invalid_requestThe username breaks WhatsApp's rules.
502upstream_errorMeta refused or did not answer.

curl -X PUT https://nodium.io/api/v1/channels/<id>/username \  -H "Authorization: Bearer $NODIUM_KEY" \  -H "Content-Type: application/json" \  -d '{    "username": "…"  }'

Response

200 OK

{ "data": { "username": "…", "status": "…" }}