Adjuntar archivos

Para enviar una imagen o un documento no hace falta publicarlo en una URL: podés subirlo a Arplyx con POST /media y referenciarlo desde POST /messages por mediaId. Arplyx sube el archivo a la API de Meta y envía el mensaje por id.

Subir el archivo: `POST /media`

multipart/form-data con un único campo file. Autenticado con tu API key, como el resto de la API.

curl -X POST https://api.arplyx.com/media \
  -H "x-api-key: $ARPLYX_API_KEY" \
  -F "file=@./factura-A-0001-00012345.pdf"

Respuesta 201 Created:

{
  "mediaId": "3f1c9a3e-6c2e-4d4b-9a1f-2b6f8f7c1d90",
  "mimetype": "application/pdf",
  "sizeBytes": 48213,
  "filename": "factura-A-0001-00012345.pdf",
  "expiresAt": "2026-09-08T13:00:00.000Z"
}

Campo	Detalle
`mediaId`	El id a usar en `content.image.mediaId` o `content.document.mediaId`.
`mimetype`	Tipo detectado por Arplyx: primero por el contenido (JPEG, PNG, PDF), después por el Content-Type de la parte y por la extensión del nombre.
`filename`	Nombre con el que se subió. Es el nombre que ve el destinatario en un documento, salvo que indiques otro en `content.document.filename`.
`expiresAt`	Vencimiento si no se usa en ningún mensaje (1 hora). Ver retención.

Enviar usando el `mediaId`

{
  "externalId": "factura-A-0001-00012345",
  "channel": "whatsapp_meta",
  "to": { "type": "phone", "phoneE164": "+15550100123" },
  "content": {
    "type": "document",
    "document": { "mediaId": "3f1c9a3e-6c2e-4d4b-9a1f-2b6f8f7c1d90" },
    "caption": "Te adjunto la factura de este mes."
  },
  "whatsappAccountId": "TU_ACCOUNT_ID"
}

mediaId y url son excluyentes: en cada envío indicás uno de los dos. Para imágenes, el archivo subido tiene que ser JPEG o PNG; si no, POST /messages responde 422 invalid_media.

Un mismo mediaId puede usarse en varios mensajes mientras el archivo exista, pero no está pensado como almacenamiento: apenas todos los mensajes que lo referencian terminan, el archivo se borra.

Retención

Arplyx guarda el archivo solo lo que dura el envío:

Se borra apenas el mensaje que lo usa llega a un estado terminal: sent (o delivered/read) o failed definitivo. En el caso normal, segundos después de encolarlo.
Mientras un mensaje que lo usa está pending o queued (reintentos incluidos), se conserva.
Si subís un archivo y nunca lo usás, se borra a la hora.
Nada sobrevive al TTL del mensaje (por defecto 7 días, máximo 30).

Si necesitás mandar el mismo archivo más adelante, volvé a subirlo. Un mediaId ya borrado devuelve 422 invalid_media en POST /messages, y si se borra entre que encolaste y se envió (no debería pasar), el mensaje termina en failed con MEDIA_UNAVAILABLE.

Límites

Límite	Valor
Tamaño máximo por archivo	20 MB (`413 media_too_large`). Para imágenes, WhatsApp acepta hasta 5 MB.
Archivos pendientes de uso por cliente	200 (`429 media_pending_limit`). Se liberan al enviarse o a la hora.
Formatos de imagen	JPEG, PNG.
Formatos de documento	PDF, Word, Excel, PowerPoint y texto plano.

Con los SDKs

Los SDKs hacen el upload por vos si pasás los bytes del archivo:

Node.jsPython

import { readFile } from 'node:fs/promises';

await arplyx.sendMessage({
  externalId: 'factura-A-0001-00012345',
  to: '+15550100123',
  channel: 'whatsapp_meta',
  whatsappAccountId: 'TU_ACCOUNT_ID',
  document: {
    file: await readFile('./factura.pdf'),
    filename: 'Factura A-0001-00012345.pdf',
    caption: 'Te adjunto la factura de este mes.',
  },
});

client.send_message(
    external_id="factura-A-0001-00012345",
    to="+15550100123",
    channel="whatsapp_meta",
    whatsapp_account_id="TU_ACCOUNT_ID",
    document={"path": "./factura.pdf", "filename": "Factura A-0001-00012345.pdf", "caption": "Te adjunto la factura de este mes."},
)

También podés hacer el upload aparte (arplyx.uploadMedia(...) / client.upload_media(...)) y reusar el mediaId en varios envíos. Desde un agente por MCP, la tool send_message acepta path con la ruta local del archivo.