Envío de archivo

Enviar un archivo por la API son dos llamadas: primero sube el archivo y recibe un identificador, luego envía el mensaje referenciando ese identificador.

1. POST /v1/resource/upload-attachment   (multipart)  →  { "_id": "..." }
2. POST /v1/messages/send-document       (JSON, con el _id del paso 1)

No existe una llamada única que reciba el archivo y lo envíe. Intentar mandar el archivo directo al endpoint de envío resulta en error. Todo esto usa el scope messages:create, el mismo del envío de texto. Si su API key ya envía mensajes, ya envía archivos.

Paso 1: subir el archivo

Envíe el archivo en multipart/form-data

Dos campos obligatorios: file con el binario y fileType con la categoría.

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"

Guarde el _id de la respuesta

La respuesta trae el registro del adjunto. El campo que importa para el paso 2 es el _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"
  }
}

El adjunto queda guardado y puede reutilizarse. Para enviar el mismo archivo a varios contactos, súbalo una vez y use el mismo _id en cada envío.

Valores de `fileType`

`fileType`	Formatos aceptados	Endpoint de envío
`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`

El fileType de la subida debe coincidir con el endpoint de envío. Subir como DOCUMENT e intentar enviar por send-image no funciona.

Paso 2: enviar a la conversación

El cuerpo es JSON, con la conversación de destino y el objeto message:

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": "Aquí tiene el presupuesto que acordamos.",
      "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: "Aquí tiene el presupuesto que acordamos.",
      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": "Aquí tiene el presupuesto que acordamos.",
            "contentType": "DOCUMENT",
            "attachment": upload["_id"],
        },
    },
)

Campos de `message`

Campo	Tipo	Obligatorio	Descripción
`attachment`	string	Sí	El `_id` devuelto por la subida.
`contentType`	string	Sí	`DOCUMENT`, `IMAGE`, `VIDEO` o `AUDIO`, según el endpoint.
`content`	string	No	Texto que acompaña al archivo, como leyenda.
`quoteSourceId`	string	No	Id del mensaje que quiere citar (vea abajo).

El campo contentAttributes.inReplyToExternalId está descontinuado y sin efecto. Para responder citando un mensaje, use quoteSourceId.

Citar un mensaje

quoteSourceId espera el id del mensaje en el canal, no el _id de Nuvia. Enviar el _id no cita nada y no devuelve error.

Canal	Qué es el id
WhatsApp (Meta)	`wamid`
Evolution	`key.id`
LinkedIn (Unipile)	`message_id`

Ese valor llega en el campo source_id de cada mensaje devuelto por GET /v1/messages/conversation/{id}. Léalo de ahí y envíelo de vuelta en quoteSourceId. El mensaje citado tiene que pertenecer a la misma conversación.

Límites

Subida: hasta 100 MB por archivo.
WhatsApp: imagen hasta 5 MB, audio y video hasta 16 MB, documento hasta 100 MB. El límite del canal aplica aunque la subida haya aceptado el archivo, así que un video de 50 MB se sube pero no llega al contacto.
Formatos: solo los aceptados por WhatsApp, listados en la tabla anterior.

Errores comunes

Situación	Respuesta
API key sin el scope `messages:create`	`403`
Archivo por encima de 100 MB	`413`, y nada se almacena
`fileType` ausente o fuera de la lista	`400`
`attachment` que no existe, o de otra empresa	`400`
Token ausente, inválido o revocado	`401`

Primeros pasos

Guías

Paso 1: subir el archivo

Valores de `fileType`

Paso 2: enviar a la conversación

Campos de `message`

Citar un mensaje

Límites

Errores comunes

Próximos pasos

Referencia de la API

Ejemplos de integración

​Paso 1: subir el archivo

​Valores de fileType

​Paso 2: enviar a la conversación

​Campos de message

​Citar un mensaje

​Límites

​Errores comunes

​Próximos pasos

Referencia de la API

Ejemplos de integración

Paso 1: subir el archivo

Valores de `fileType`

Paso 2: enviar a la conversación

Campos de `message`

Citar un mensaje

Límites

Errores comunes

Próximos pasos