File sending

Sending a file through the API is two calls: first you upload the file and get an identifier, then you send the message referencing that identifier.

1. POST /v1/resource/upload-attachment   (multipart)  →  { "_id": "..." }
2. POST /v1/messages/send-document       (JSON, with the _id from step 1)

There’s no single call that receives the file and sends it. Trying to send the file directly to the sending endpoint results in an error. Everything here uses the messages:create scope, the same one used for sending text. If your key already sends messages, it already sends files.

Step 1: upload the file

Send the file as multipart/form-data

Two required fields: file with the binary and fileType with the category.

cURL

curl -X POST https://api.nuvia.ai/v1/resource/upload-attachment \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -F "file=@orcamento.pdf" \
  -F "fileType=DOCUMENT"

Save the _id from the response

The response carries the attachment record. The field that matters for step 2 is the _id:

{
  "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
  "extension": "pdf",
  "external_url": "https://s3.amazonaws.com/bucket/orcamento.pdf",
  "file_type": "DOCUMENT",
  "meta": {
    "mimeType": "application/pdf",
    "size": 102400,
    "fileName": "orcamento.pdf"
  }
}

The attachment stays saved and can be reused. To send the same file to several contacts, upload it once and use the same _id in each send.

`fileType` values

`fileType`	Accepted formats	Sending endpoint
`DOCUMENT`	PDF, DOC, DOCX, XLS, XLSX, PPT, TXT	`POST /v1/messages/send-document`
`IMAGE`	JPG, PNG, GIF, WEBP	`POST /v1/messages/send-image`
`VIDEO`	MP4, 3GP	`POST /v1/messages/send-video`
`AUDIO`	MP3, OGG, AAC, AMR	`POST /v1/messages/send-audio`
`STICKER`	WEBP	`POST /v1/messages/send-image`

The fileType from the upload must match the sending endpoint. Uploading as DOCUMENT and trying to send through send-image doesn’t work.

Step 2: send to the conversation

The body is JSON, with the target conversation and the message object:

curl -X POST https://api.nuvia.ai/v1/messages/send-document \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "65f1a2b3c4d5e6f7a8b9c0d3",
    "message": {
      "content": "Here's the quote we agreed on.",
      "contentType": "DOCUMENT",
      "attachment": "65f1a2b3c4d5e6f7a8b9c0d1"
    }
  }'

const upload = new FormData();
upload.append("file", file);
upload.append("fileType", "DOCUMENT");

const { _id } = await fetch("https://api.nuvia.ai/v1/resource/upload-attachment", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NUVIA_API_KEY}` },
  body: upload,
}).then((r) => r.json());

await fetch("https://api.nuvia.ai/v1/messages/send-document", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversationId,
    message: {
      content: "Here's the quote we agreed on.",
      contentType: "DOCUMENT",
      attachment: _id,
    },
  }),
});

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"}

with open("orcamento.pdf", "rb") as f:
    upload = requests.post(
        "https://api.nuvia.ai/v1/resource/upload-attachment",
        headers=headers,
        files={"file": f},
        data={"fileType": "DOCUMENT"},
    ).json()

requests.post(
    "https://api.nuvia.ai/v1/messages/send-document",
    headers=headers,
    json={
        "conversationId": conversation_id,
        "message": {
            "content": "Here's the quote we agreed on.",
            "contentType": "DOCUMENT",
            "attachment": upload["_id"],
        },
    },
)

`message` fields

Field	Type	Required	Description
`attachment`	string	Yes	The `_id` returned by the upload.
`contentType`	string	Yes	`DOCUMENT`, `IMAGE`, `VIDEO`, or `AUDIO`, matching the endpoint.
`content`	string	No	Text that accompanies the file, such as a caption.
`quoteSourceId`	string	No	Id of the message you want to quote (see below).

The contentAttributes.inReplyToExternalId field is deprecated and has no effect. To reply quoting a message, use quoteSourceId.

Quoting a message

quoteSourceId expects the id of the message on the channel, not Nuvia’s _id. Sending the _id quotes nothing and returns no error.

Channel	What the id is
WhatsApp (Meta)	`wamid`
Evolution	`key.id`
LinkedIn (Unipile)	`message_id`

That value arrives in the source_id field of every message returned by GET /v1/messages/conversation/{id}. Read it from there and send it back in quoteSourceId. The quoted message has to belong to the same conversation.

Limits

Upload: up to 100 MB per file.
WhatsApp: images up to 5 MB, audio and video up to 16 MB, documents up to 100 MB. The channel limit applies even if the upload accepted the file, so a 50 MB video uploads but doesn’t reach the contact.
Formats: only those accepted by WhatsApp, listed in the table above.

Common errors

Situation	Response
Key without the `messages:create` scope	`403`
File over 100 MB	`413`, and nothing is stored
`fileType` missing or not in the list	`400`
`attachment` that doesn’t exist, or belongs to another company	`400`
Token missing, invalid, or revoked	`401`

Getting started

Guides

Step 1: upload the file

`fileType` values

Step 2: send to the conversation

`message` fields

Quoting a message

Limits

Common errors

Next steps

API reference

Integration examples

​Step 1: upload the file

​fileType values

​Step 2: send to the conversation

​message fields

​Quoting a message

​Limits

​Common errors

​Next steps

API reference

Integration examples

Step 1: upload the file

`fileType` values

Step 2: send to the conversation

`message` fields

Quoting a message

Limits

Common errors

Next steps