Saltar al contenido principal
Actualizado el Jul 26, 2026

Subir archivos (API y MCP)

Lo que aprenderás
  • Cómo subir una imagen o archivo de forma programática y obtener una referencia reutilizable
  • El flujo de subida REST en dos pasos (y la herramienta MCP de un paso)
  • Dónde usar la referencia {bucket, fullPath} resultante

Muchas funciones de AutoTalk usan medios — una imagen de producto para un catálogo de WhatsApp, un mensaje multimedia, una foto de perfil. En lugar de alojar esos archivos por tu cuenta, súbelos a AutoTalk una vez y obtén una referencia de almacenamiento propia que puedes reutilizar en todas partes:

{ "bucket": "autotalk-prod", "fullPath": "companies/<id>/api/images/storage_manual_upload/<id>.png" }

Esa referencia {bucket, fullPath} es aceptada por send_message, campos de documentos Dynadata y funciones como createWhatsappWebEvoProduct (en su array images) — consulta Dónde usar la referencia.

REST: la subida en dos pasos​

La subida por la API REST es un PUT firmado, de modo que los bytes van directo al almacenamiento. Autentica cada llamada con tu x-api-key.

1. Reserva una URL de subida firmada​

curl -X POST https://api.autotalk.io/v1/storage/upload-url \
  -H "x-api-key: sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mimeType": "image/png",
    "fileSize": 41161,
    "fileName": "product.png",
    "purpose": "whatsapp_catalog_product_image"
  }'

La respuesta te da una uploadUrl de corta duración, los requiredHeaders exactos y un uploadIntentId:

{
  "success": true,
  "uploadIntentId": "...",
  "uploadUrl": "https://storage.autotalk.io/...&X-Amz-Signature=...",
  "uploadMode": "signed_put",
  "bucket": "autotalk-prod",
  "fullPath": "companies/<id>/api/images/whatsapp_catalog_product_image/<id>.png",
  "category": "images",
  "requiredHeaders": { "Content-Type": "image/png", "Content-Length": "41161", "x-amz-meta-...": "..." }
}

2. Haz el PUT de los bytes​

Sube el archivo directamente a uploadUrl, enviando todas las entradas de requiredHeaders exactamente como se indican. El tamaño del cuerpo debe coincidir con fileSize.

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: image/png" \
  -H "Content-Length: 41161" \
  --data-binary @product.png

3. Finaliza​

curl -X POST https://api.autotalk.io/v1/storage/upload-complete \
  -H "x-api-key: sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "uploadIntentId": "<uploadIntentId>" }'

La respuesta es tu referencia reutilizable:

{ "success": true, "bucket": "autotalk-prod", "fullPath": "companies/<id>/api/images/whatsapp_catalog_product_image/<id>.png", "size": 41161, "contentType": "image/png", "category": "images", "fileName": "product.png" }

Para leer un objeto almacenado más tarde, llama a GET /v1/storage/url?path=<fullPath> para obtener una URL de descarga de corta duración.

MCP: begin/complete o inline en un paso​

Si te conectas mediante el servidor MCP, usa las herramientas de archivo:

  • begin_file_upload({fileName, mimeType, fileSize}) → haz el PUT HTTP a la uploadUrl devuelta → complete_file_upload({uploadIntentId}). Devuelve {bucket, fullPath}. Úsalo para cualquier tamaño.
  • upload_file_inline({fileName, mimeType, data}) — pasa los bytes codificados en base64 directamente y obtén {bucket, fullPath} en una sola llamada. Práctico para archivos pequeños (≤ ~1 MB); los archivos más grandes deben usar el flujo en dos pasos.

Dónde usar la referencia​

Pasa {bucket, fullPath} (o, para images, una URL pública o la referencia) donde se acepten medios:

  • Enviar un mensaje multimedia — send_message body.file = {bucket, fullPath}.
  • Catálogo de WhatsApp — createWhatsappWebEvoProduct / updateWhatsappWebEvoProduct images: [{bucket, fullPath}, ...].
  • Foto de perfil / grupo — updateWhatsappWebEvoProfilePicture picture, updateWhatsappWebEvoGroupPicture image.
  • Campos de documento Dynadata — cualquier campo de objeto de almacenamiento (por ejemplo, la imagen de un documento).

Propósitos y límites​

  • purpose (opcional, por defecto storage_manual_upload) indica para qué es el archivo. Valores permitidos: storage_manual_upload, whatsapp_catalog_product_image, template_message_media, chat_media_upload, scheduled_message_media, contact_avatar, company_logo.
  • Los bytes subidos cuentan para la cuota de almacenamiento de tu empresa; una subida que la superaría devuelve 409.
  • Los archivos viven bajo el prefijo de tu empresa; solo puedes referenciar objetos de tu propio inquilino (tenant).

Próximos pasos​

Última actualización en
En esta página