> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Enviar Archivo por Mensaje
> Servicio para enviar archivos adjuntos en un mensaje de WhatsApp al contacto.
## Descripcion
Envia un archivo multimedia (imagen, audio, video o documento) a un contacto por WhatsApp. El archivo puede enviarse de dos formas:
1. **Por URL** (`contentUrl`): Proporciona una URL publica del archivo. El servidor descarga el archivo, lo sube a almacenamiento y lo envia al contacto.
2. **Por archivo** (`contentFile`): Sube directamente el archivo como `multipart/form-data`.
Si usas **Workers**, puedes enviar archivos multimedia usando `plz.whatsapp.sendMedia()` que internamente utiliza este endpoint con `contentUrl`.
## Parametros
| Parametro | Tipo | Requerido | Descripcion |
| --------------------- | ------ | ----------- | ------------------------------------------------------------------------ |
| `workspaceId` | string | Si | ID del workspace |
| `recipientPhone` | string | Si | Numero de telefono del destinatario (con codigo de pais) |
| `contactId` | string | Si | ID del contacto en la plataforma |
| `contentUrl` | string | Condicional | URL publica del archivo a enviar. Requerido si no se envia `contentFile` |
| `contentFile` | file | Condicional | Archivo binario. Requerido si no se envia `contentUrl` |
| `content` | string | No | Caption o texto que acompana al archivo |
| `externalReferenceId` | string | No | Identificador externo opcional para rastreo |
## Tipos de archivo soportados
### Imagenes
* `image/jpeg`, `image/png`
### Audio
* `audio/aac`, `audio/amr`, `audio/mpeg`, `audio/mp4`, `audio/ogg`, `audio/webm`, `audio/x-m4a`
* Los audios se convierten automaticamente a MP3
### Video
* `video/mp4`, `video/3gpp`
### Documentos
* `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.*`
* Y cualquier otro tipo de archivo se envia como documento
## Ejemplo con URL
```bash theme={null}
curl -X POST https://api.plazbot.com/api/message/files \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "workspaceId=YOUR_WORKSPACE_ID" \
-F "recipientPhone=5491123456789" \
-F "contactId=CONTACT_ID" \
-F "contentUrl=https://example.com/factura.pdf" \
-F "content=Aqui tienes tu factura"
```
## Ejemplo con archivo
```bash theme={null}
curl -X POST https://api.plazbot.com/api/message/files \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "workspaceId=YOUR_WORKSPACE_ID" \
-F "recipientPhone=5491123456789" \
-F "contactId=CONTACT_ID" \
-F "contentFile=@/path/to/image.png" \
-F "content=Mira esta imagen"
```
## Uso desde Workers
```typescript theme={null}
// Enviar imagen desde URL
await plz.whatsapp.sendMedia({
to: '5491123456789',
url: 'https://example.com/producto.jpg',
caption: 'Foto del producto'
})
// Enviar PDF
await plz.whatsapp.sendMedia({
to: '5491123456789',
url: 'https://example.com/factura.pdf',
filename: 'factura-001.pdf',
caption: 'Tu factura esta lista'
})
```
El servidor detecta automaticamente el tipo de archivo basandose en la extension de la URL. Si el archivo es un audio, se convierte automaticamente a formato MP3 para compatibilidad con WhatsApp.
## OpenAPI
````yaml POST /api/message/files
openapi: 3.1.0
info:
title: Plazbot
description: >-
Documentacion completa de la API de Plazbot. Incluye todos los servicios
para gestion de contactos, conversaciones, mensajes, oportunidades, tareas,
plantillas, agentes de IA, usuarios y workspaces.
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.plazbot.com
description: Servidor de produccion de Plazbot
security:
- bearerAuth: []
tags:
- name: automation
description: Servicios de automatizacion y nodos de IA
- name: agent
description: Servicios para gestion de Agentes de Inteligencia Artificial
- name: contact
description: Servicios para gestion de contactos del workspace
- name: conversation
description: Servicios para gestion de conversaciones y campanas
- name: message
description: Servicios para envio y gestion de mensajes
- name: opportunity
description: Servicios para gestion de oportunidades de negocio
- name: task
description: Servicios para gestion de tareas
- name: template
description: Servicios para gestion de plantillas de WhatsApp
- name: user
description: Servicios para gestion de usuarios y autenticacion
- name: workspace
description: Servicios para gestion de workspaces
paths:
/api/message/files:
post:
tags:
- message
summary: Enviar Archivos en Mensaje
description: >-
Servicio para enviar archivos adjuntos en un mensaje de WhatsApp al
contacto.
operationId: sendMessageFiles
parameters:
- name: contactId
in: query
description: ID del contacto
required: false
schema:
type: string
- name: workspaceId
in: query
description: Identificador del workspace
required: false
schema:
type: string
- name: recipientPhone
in: query
description: Numero de WhatsApp del destinatario
required: false
schema:
type: string
- name: x-workspace-id
in: header
description: Identificador del workspace
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
contentFile:
type: string
format: binary
description: Archivo a enviar
required:
- contentFile
responses:
'200':
description: Archivo enviado exitosamente
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Indica si la operacion fue exitosa
code:
type: integer
description: Codigo HTTP de la respuesta
errorCode:
type:
- string
- 'null'
description: Codigo de error, null si no hay error
message:
type: string
description: Mensaje descriptivo del resultado
data:
type:
- object
- 'null'
description: Datos de la respuesta
required:
- success
- code
- errorCode
- message
- data
'400':
description: Solicitud incorrecta - Datos invalidos o faltantes
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: No autorizado - Token Bearer requerido o invalido
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Recurso no encontrado
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Error interno del servidor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: []
components:
schemas:
ErrorResponse:
type: object
description: Respuesta de error estandar de la API
properties:
success:
type: boolean
description: Siempre false en errores
code:
type: integer
description: Codigo HTTP del error
errorCode:
type:
- string
- 'null'
description: Codigo de error especifico
message:
type: string
description: Mensaje descriptivo del error
required:
- success
- code
- message
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Token de autenticacion Bearer. Obtenga el token usando el endpoint
/api/user/login
````