Media

3 endpoints in this family.

List received and sent files

GET/api/v1/media

Returns the files Nodium kept a copy of — images, videos, sounds and documents — most recent first. The file itself is downloaded with GET /messages/{messageId}/media.

Query parameters

kindstring
Only this family of files. document is everything that is not an image, a video or a sound.
imagevideoaudiodocument
fromstring
Only files received or sent from this instant (ISO 8601).
tostring
Only files received or sent before this instant (ISO 8601).
limitinteger
How many to return.
cursorstring
Opaque cursor from the previous page. Omit for the first page.

Response

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

data.itemsobject[]
The files, most recent first.
Show fields
- messageIdstring
  The message that carries the file.
- conversationIdstring
  Its conversation.
- directionstring
  Received or sent.
  inboundoutbound
- kindstring
  The family of the file.
  imagevideoaudiodocument
- mimeTypestring
  Its media type; null when unknown.
- filenamestring
  Its name, when the sender gave one.
- createdAtstring
  ISO 8601.
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.

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

Response

200 OK

{  "data": {    "items": [      {        "messageId": "…",        "conversationId": "…",        "direction": "inbound",        "kind": "image",        "mimeType": "…",        "filename": "…",        "createdAt": "…"      }    ],    "nextCursor": "…",    "hasMore": true,    "total": 0  }}

Upload a file to send

POST/api/v1/media

Uploads an image, video, audio file or document, as multipart/form-data, and returns a mediaId. Send it with POST /messages (type set to the returned kind).

The mediaId is valid for 7 days (expiresAt); after that, upload the file again. It belongs to the client you act on and can be sent to as many people as you like. Files are at most 4 MB. Nothing is sent to WhatsApp by this call: the file goes to Meta when you send it, from the number you choose.

Limited to 30 uploads per minute per key and client.

Body

filestringrequired
The file itself, as a multipart part named file.

Response

The `mediaId`, its kind, and when it expires.

data.mediaIdstring
Pass it as mediaId to POST /messages.
data.kindstring
The type to send it with.
imagevideoaudiodocument
data.mimeTypestring
Its media type.
data.filenamestring
Its name, as uploaded.
data.sizeinteger
Its size in bytes.
data.expiresAtstring
ISO 8601. Until then the mediaId can be sent.

Refusals

422file_missingNo file was sent, or it is empty.
413file_too_largeThe file is over 4 MB.
415file_type_refusedThis type of file cannot be sent on WhatsApp through Nodium.
402storage_quotaThe media storage included in your plan is full and your plan does not bill extra gigabytes.
429rate_limitedMore than 30 uploads in a minute for this key and client.

curl -X POST https://nodium.io/api/v1/media \  -H "Authorization: Bearer $NODIUM_KEY" \  -H "Content-Type: application/json" \  -d '{    "file": "…"  }'

Response

200 OK

{  "data": {    "mediaId": "…",    "kind": "image",    "mimeType": "…",    "filename": "…",    "size": 0,    "expiresAt": "…"  }}

Remove the file of a message

DEL/api/v1/media/{id}

Deletes the copy Nodium kept of the file. The message stays, with its text and its delivery data. The file cannot be recovered afterwards: WhatsApp deletes received media after seven days.

Path parameters

idstring
The id of the message that carries the file.

Response

Confirmation that the file is gone.

data.removedboolean
Always true.

Refusals

502upstream_errorThe storage refused the deletion; nothing changed, try again.

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

Response

200 OK

{ "data": { "removed": true }}