Conversations

5 endpoints in this family.

List conversations

GET/api/v1/conversations

Returns conversations, most recently active first, with a cursor for the next page. Each row carries its last message and the state of the 24-hour service window.

Query parameters

limitinteger
How many to return. Defaults to a sensible page size.
cursorstring
Opaque cursor from the previous page. Omit for the first page.
channelIdstring
Only conversations on this channel.
contactIdstring
Only conversations of this contact.
phonestring
Only conversations of the contact who has this phone number, in any writing (+33 6 12 34 56 78, 0033612345678, 33612345678). At least 6 digits; the whole number, not a part of it.

Response

A page of conversations and the cursor for the next one.

data.itemsConversation[]
The conversations, most recent inbound first.
data.nextCursorstring
Pass it as cursor for the next page; null at the end.
data.hasMoreboolean
Whether another page exists.
data.totalinteger
How many match, on the first page only; null after.

Refusals

422invalid_request`phone` has fewer than 6 digits, or `channelId` / `contactId` is not an id.

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

Response

200 OK

{ "data": { "items": [ {} ], "nextCursor": "…", "hasMore": true, "total": 0 }}

Get one conversation

GET/api/v1/conversations/{id}

Returns the conversation with its contact, its channel and the state of the 24-hour service window.

Path parameters

idstring
The conversation id.

Response

The conversation.

data.idstring
The conversation id.
data.channelIdstring
The channel it lives on.
data.channelTypestring
The kind of channel.
whatsapp
data.channelNamestring
The channel's name in Nodium.
data.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.
data.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.
data.lastInboundAtstring
When the contact last wrote, ISO 8601. This opens the 24-hour window.
data.createdAtstring
ISO 8601.
data.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.

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

Response

200 OK

{  "data": {    "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": "…"    }  }}

List the messages of a conversation

GET/api/v1/conversations/{id}/messages

Returns messages oldest first; paging walks back into the past.

Path parameters

idstring
The conversation id.

Query parameters

limitinteger
How many messages to return.
cursorstring
Opaque cursor from the previous page; walks back into the past.

Response

A page of messages.

data.itemsMessage[]
The messages, oldest first.
data.nextCursorstring
Pass it as cursor to go further back; null at the start of the thread.
data.hasMoreboolean
Whether older messages exist.

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

Response

200 OK

{ "data": { "items": [ {} ], "nextCursor": "…", "hasMore": true }}

Send a read receipt

POST/api/v1/conversations/{id}/read

Sends a read receipt to the customer — their two ticks turn blue — for the last message they sent. Nothing changes on the Nodium side.

Path parameters

idstring
The conversation id.

Response

An acknowledgement.

data.okboolean
The receipt was queued.

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

Response

200 OK

{ "data": { "ok": true }}

Show "typing…" to the customer

POST/api/v1/conversations/{id}/typing

Shows the typing indicator in the customer's WhatsApp while your software prepares the answer. It disappears when your message arrives, or after 25 seconds — call it again for a longer wait.

WhatsApp ties it to the read receipt: the customer's last message also turns blue. Nothing changes in Nodium.

Path parameters

idstring
The conversation id.

Response

Whether the indicator was shown.

data.shownboolean
false when the customer has not written yet: there is nothing to attach it to.

Refusals

422not_whatsappOnly WhatsApp has a typing indicator.
502upstream_errorWhatsApp refused it; `detail` carries its reason.

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

Response

200 OK

{ "data": { "shown": true }}