Shared shapes

The objects endpoints return — a conversation, a message, a contact, an app… described once, here.

`Conversation`

A conversation: one contact on one WhatsApp number — the 24-hour window and the delivery receipts.

idstring
The conversation id.
channelIdstring
The channel it lives on.
channelTypestring
The kind of channel.
whatsapp
channelNamestring
The channel's name in Nodium.
contactobject
Who you are talking to.
Show fields
- idstring
  The contact id.
- displayNamestring
  Their name, or null.
- identitystring
  Their phone number, or their WhatsApp user id when the number is hidden.
- identityKindstring
  What identity is.
  phoneemailexternal
- blockedboolean
  Blocked contacts are kept out of the inbox.
windowobject
The WhatsApp 24-hour customer service window.
Show fields
- appliesboolean
  false outside WhatsApp.
- openboolean
  Whether free text can be sent now. Always true when the rule does not apply.
- expiresAtstring
  When it closes, ISO 8601, or null.
- minutesLeftinteger
  Minutes left, 0 when closed, null when the rule does not apply.
lastInboundAtstring
When the contact last wrote, ISO 8601. This opens the 24-hour window.
createdAtstring
ISO 8601.
lastMessageobject
The latest message, or null.
Show fields
- idstring
  The message id.
- directionstring
  From the contact, or to them.
  inboundoutbound
- textContentstring
  Its text.
- statusstring
  Its delivery status.
- createdAtstring
  ISO 8601.

Conversation

Example

{  "id": "…",  "channelId": "…",  "channelType": "whatsapp",  "channelName": "…",  "contact": {    "id": "…",    "displayName": "…",    "identity": "…",    "identityKind": "phone",    "blocked": true  },  "window": {    "applies": true,    "open": true,    "expiresAt": "…",    "minutesLeft": 0  },  "lastInboundAt": "…",  "createdAt": "…",  "lastMessage": {    "id": "…",    "direction": "inbound",    "textContent": "…",    "status": "…",    "createdAt": "…"  }}

`Message`

One message, in either direction.

idstring
The message id.
conversationIdstring
Its conversation.
channelTypestring
The kind of channel.
whatsapp
directionstring
inbound from the contact, outbound to them.
inboundoutbound
senderstring
Who speaks: the contact, your software (api, through a key), a person in the console (user), or Nodium (system).
contactapiusersystem
senderNamestring
The person's name, or your key's label.
apiKeyIdstring
The key that sent it, when it went through the API.
typestring
text, template, interactive, image, audio, document…
textContentstring
Its text. For a template, the rendered text.
mediaUrlstring
Where to download its file (GET /messages/{id}/media), or null.
statusstring
Delivery status. queued: waiting to leave (queue: true).
queuedsendingsentdeliveredreadfailed
providerMessageIdstring
The id at the messaging provider (WhatsApp wamid), or null.
errorstring
Why it failed, as the provider said, or null.
errorInfoobject
The failure explained, when status is failed and the provider gave a code; otherwise null. A send can answer HTTP 200 or 201 with status: "failed": test status, then read this.
Show fields
- codeinteger
  The provider's error code (Meta's, for example 131047).
- titlestring
  What happened, in a sentence.
- actionstring
  What to do about it. When actor is client, written to be passed on to your client as is.
- actorstring
  Who acts: you (your code or console), client (the owner of the number), nodium, or wait (the refusal is temporary: nobody needs to act).
  youclientnodiumwait
formobject
The buttons or list sent with it, or null.
replyobject
For a tapped button or chosen list row: { id, title }. Otherwise null.
locationobject
A location the contact sent: { latitude, longitude, name, address }, or null.
originstring
phone when the message was written from the WhatsApp Business app of a coexistence number, otherwise null.
importedboolean
True for a message taken from the phone's chat history (coexistence), not received live.
createdAtstring
ISO 8601.

Message

Example

{  "id": "…",  "conversationId": "…",  "channelType": "whatsapp",  "direction": "inbound",  "sender": "contact",  "senderName": "…",  "apiKeyId": "…",  "type": "…",  "textContent": "…",  "mediaUrl": "…",  "status": "queued",  "providerMessageId": "…",  "error": "…",  "errorInfo": {    "code": 0,    "title": "…",    "action": "…",    "actor": "you"  },  "form": {},  "reply": {},  "location": {},  "origin": "…",  "imported": true,  "createdAt": "…"}

`SendResult`

What a send returns.

conversationIdstring
The conversation the message belongs to — opened by this call, or reused.
messageMessage
duplicateboolean
true when this idempotencyKey was already used: the message returned is the first one, nothing was sent again.

SendResult

Example

{  "conversationId": "…",  "message": {    "id": "…",    "conversationId": "…",    "channelType": "whatsapp",    "direction": "inbound",    "sender": "contact",    "senderName": "…",    "apiKeyId": "…",    "type": "…",    "textContent": "…",    "mediaUrl": "…",    "status": "queued",    "providerMessageId": "…",    "error": "…",    "errorInfo": {},    "form": {},    "reply": {},    "location": {},    "origin": "…",    "imported": true,    "createdAt": "…"  },  "duplicate": true}

`Contact`

A person you talk to.

idstring
The contact id.
displayNamestring
Their name, or null.
phonestring
Their phone number, E.164 digits, or null.
emailstring
Their email address, or null.
externalIdstring
Your own id for them, or null.
optInAtstring
When they agreed to receive messages, or null.
optOutAtstring
When they withdrew — on WhatsApp by tapping "Stop" — or null. It overrides optInAt.
blockedboolean
Blocked contacts receive nothing.
conversationCountinteger
How many conversations they have.
createdAtstring
ISO 8601.
updatedAtstring
ISO 8601.

Contact

Example

{  "id": "…",  "displayName": "…",  "phone": "…",  "email": "…",  "externalId": "…",  "optInAt": "…",  "optOutAt": "…",  "blocked": true,  "conversationCount": 0,  "createdAt": "…",  "updatedAt": "…"}

`Channel`

A WhatsApp number the workspace speaks from.

idstring
The channel id — the channelId you send from.
typestring
The kind of channel.
whatsapp
namestring
Its name in Nodium.
identitystring
Its public identity: the business phone number id.
isActiveboolean
An inactive channel neither sends nor receives.
qualityRatingstring
WhatsApp quality rating: GREEN, YELLOW, RED, or null.
messagingLimitstring
Meta's sending tier, or null.
isTestboolean
A test channel: the sandbox (the shared Nodium number) or the demo channel.
paymentMissingboolean
Meta refused a paid message because the client's WhatsApp account has no payment method (error 131042). The client adds one in WhatsApp Manager; it clears once a template is delivered.

Channel

Example

{  "id": "…",  "type": "whatsapp",  "name": "…",  "identity": "…",  "isActive": true,  "qualityRating": "…",  "messagingLimit": "…",  "isTest": true,  "paymentMissing": true}

`Template`

A WhatsApp message template.

idstring
The template id — the templateId you send.
namestring
Its name at Meta.
languagestring
Its language code, e.g. fr.
categorystring
Meta's category. Marketing ones are refused to contacts who opted out.
UTILITYMARKETINGAUTHENTICATION
statusstring
Where it stands at Meta, across its client's WhatsApp accounts. Only approved can be sent. failed: the deposit at Meta did not happen; deploy again.
draftnot_deployedno_numbersubmittedapprovedrejectedpauseddisabledfailed
clientIdstring
The client it belongs to.
deployedAtstring
When it was first deployed, ISO 8601; null for a draft.
headerMediaobject
Its image, video or document header: kind, sampleId, mimeType, filename, size. null for a text header or none.
authenticationobject
For an AUTHENTICATION template: securityRecommendation and codeExpirationMinutes (null = no expiry line). null for any other category.
bodystring
Its text, with {{1}}, {{2}}… placeholders. For an AUTHENTICATION template, a readable copy of the text Meta writes.
createdAtstring
ISO 8601.
updatedAtstring
ISO 8601.

Template

Example

{  "id": "…",  "name": "…",  "language": "…",  "category": "UTILITY",  "status": "draft",  "clientId": "…",  "deployedAt": "…",  "headerMedia": {},  "authentication": {},  "body": "…",  "createdAt": "…",  "updatedAt": "…"}

`WebhookSubscription`

An address Nodium calls, and for which events.

idstring
The subscription id.
urlstring
The https address called.
eventsstring[]
The events delivered; * means all.
channelIdsstring[]
The channels (numbers) whose events are delivered; empty means all channels.
labelstring
Its name.
isActiveboolean
A paused subscription receives nothing.
lastDeliveredAtstring
The last successful call, ISO 8601, or null.
lastErrorstring
What went wrong last time, or null.
previousSecretValidUntilstring
During a rotation: until when the old secret still signs. null otherwise.
createdAtstring
ISO 8601.

WebhookSubscription

Example

{  "id": "…",  "url": "…",  "events": [    "…"  ],  "channelIds": [    "…"  ],  "label": "…",  "isActive": true,  "lastDeliveredAt": "…",  "lastError": "…",  "previousSecretValidUntil": "…",  "createdAt": "…"}

`WebhookDelivery`

One event delivered — or to deliver — to one subscription.

idstring
The delivery id, also sent as X-Nodium-Delivery.
subscriptionIdstring
The subscription.
eventstring
The event name.
eventIdstring
The event's own id (evt_…), the same across redeliveries: deduplicate on it.
statusstring
failed after six attempts.
pendingdeliveredfailed
attemptsinteger
Attempts so far.
responseStatusinteger
The HTTP status your server answered, or null.
lastErrorstring
What went wrong, or null.
nextAttemptAtstring
When the next attempt is due, for a pending delivery.
createdAtstring
ISO 8601.
deliveredAtstring
ISO 8601, or null.

WebhookDelivery

Example

{  "id": "…",  "subscriptionId": "…",  "event": "…",  "eventId": "…",  "status": "pending",  "attempts": 0,  "responseStatus": 0,  "lastError": "…",  "nextAttemptAt": "…",  "createdAt": "…",  "deliveredAt": "…"}

`ApiRequest`

One call made with an API key.

idstring
The log line id.
apiKeyIdstring
The key used.
keyLabelstring
The key's label.
keyPrefixstring
The key's public prefix, nod_….
clientIdstring
The client the call acted on, or null for an account-level call (/tenants, /keys).
methodstring
HTTP method.
pathstring
The address called, without its query string.
statusinteger
The HTTP status returned.
errorCodestring
The error code returned, or null.
durationMsinteger
How long it took.
requestIdstring
The request id, also returned in errors.
createdAtstring
ISO 8601.

ApiRequest

Example

{  "id": "…",  "apiKeyId": "…",  "keyLabel": "…",  "keyPrefix": "…",  "clientId": "…",  "method": "…",  "path": "…",  "status": 0,  "errorCode": "…",  "durationMs": 0,  "requestId": "…",  "createdAt": "…"}

`ApiKey`

An API key of your account. Its secret is shown once, at creation, and never again.

idstring
The key id.
labelstring
A name for you, shown in Nodium.
keyPrefixstring
The public prefix of the secret, nod_…: enough to recognise the key, not to use it.
clientIdstring
The client the key is pinned to, or null: every client of the account, named with the Nodium-Tenant header ("My company" without it).
clientNamestring
The name of that client, or null.
isActiveboolean
false once revoked.
createdBystring
Who created it, or null when a key did.
lastUsedAtstring
Its last call, ISO 8601, or null if never used.
revokedAtstring
When it was revoked, ISO 8601, or null.
expiresAtstring
When it stops working, ISO 8601, or null if it never expires. isActive is false once this date has passed.
createdAtstring
ISO 8601.

ApiKey

Example

{  "id": "…",  "label": "…",  "keyPrefix": "…",  "clientId": "…",  "clientName": "…",  "isActive": true,  "createdBy": "…",  "lastUsedAt": "…",  "revokedAt": "…",  "expiresAt": "…",  "createdAt": "…"}

`Tenant`

One of your customers: a client of your account, isolated from the others.

idstring
The tenant id — what the Nodium-Tenant header accepts, with your externalId.
externalIdstring
Your identifier for this customer, or null. Unique in your account.
namestring
Your customer's name.
slugstring
Its address in the Nodium console. Follows the name.
statusstring
A suspended tenant neither sends nor receives.
activesuspended
localestring
Language of the hosted connect page.
fren
timezonestring
IANA time zone.
whatsappobject
Its WhatsApp state.
Show fields
- statusstring
  connected: at least one number; link_sent: a connect link is waiting; not_connected: neither.
  connectedlink_sentnot_connected
- numbersinteger
  How many WhatsApp numbers are connected.
- displayPhonestring
  The first connected number, as displayed, or null.
connectLinkobject
Its latest hosted connect link, or null if none was ever created.
Show fields
- statestring
  pending: still usable; used: it connected a number; expired: it can no longer be used.
  pendingusedexpired
- expiresAtstring
  When it stops working, ISO 8601.
- usedAtstring
  When it was used, ISO 8601, or null.
- createdAtstring
  ISO 8601.
activeThisMonthboolean
Whether it sent or received a message in the current UTC month.
eventsThisMonthinteger
Its messages in the current UTC month.
createdAtstring
ISO 8601.
updatedAtstring
ISO 8601.

Tenant

Example

{  "id": "…",  "externalId": "…",  "name": "…",  "slug": "…",  "status": "active",  "locale": "fr",  "timezone": "…",  "whatsapp": {    "status": "connected",    "numbers": 0,    "displayPhone": "…"  },  "connectLink": {    "state": "pending",    "expiresAt": "…",    "usedAt": "…",    "createdAt": "…"  },  "activeThisMonth": true,  "eventsThisMonth": 0,  "createdAt": "…",  "updatedAt": "…"}

`Error`

Every refusal of `/api/v1`.

errorobject
What went wrong.
Show fields
- statusinteger
  The HTTP status, repeated.
- codestring
  A stable code. Test this, never the text.
- messagestring
  What it means, in English: the same sentence for a given code.
- detailstring
  The specific reason for this call, in English. A few refusals not translated yet still carry a French reason. null for rate_limited, quota_exceeded and plan_limit (message and data say it all), and for an unexpected 500.
- paramstring
  The field of the body or query that was refused (to, type, location.latitude, variables.1); null when the refusal is not about one field.
- doc_urlstring
  The line of the guide « Responses and errors » that explains code; null for a code the guide does not list.
- requestIdstring
  Quote it to us if you need help.
- dataobject
  Extra facts attached to some refusals (e.g. issues).

Error

Example

{  "error": {    "status": 0,    "code": "…",    "message": "…",    "detail": "…",    "param": "…",    "doc_url": "…",    "requestId": "…",    "data": {}  }}