--- title: "Referencia de la API de archivos y tareas" description: "Sube archivos, lee sus URL y sigue trabajos largos, como exportaciones de contactos y sincronizaciones de Google Calendar, con getTask y taskUpdated." canonical_url: https://chatfuel.com/es/docs/public-api/files-and-tasks markdown_url: https://chatfuel.com/es/docs/public-api/files-and-tasks.md last_updated: 2026-10-06 lang: es site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Referencia de la API de archivos y tareas Sube archivos, lee sus URL y sigue trabajos largos, como exportaciones de contactos y sincronizaciones de Google Calendar, con getTask y taskUpdated. Los archivos y las tareas son los dos recursos auxiliares en los que se apoya el resto de la Public API de Chatfuel. Los archivos son imágenes, videos, audios y documentos: los subes por HTTP y pasas sus IDs a las mutaciones, y lees los archivos que enviaron los contactos a través de sus URL. Las tareas representan trabajos de larga duración, como una exportación de contactos a CSV o una sincronización de Google Calendar, que inicias con una mutación y luego sigues hasta que terminan. ## Cómo subir un archivo [#cómo-subir-un-archivo] Las subidas van a un endpoint HTTP aparte como `multipart/form-data`, con el mismo encabezado `Authorization: Bearer ` que las solicitudes GraphQL: | Endpoint | Para qué se usa | Rol mínimo | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------- | | `POST /api/filestorage/upload/bot?botID=…&fileType=…` | Imágenes y videos en flujos, imágenes del catálogo, fotos de especialistas, archivos CSV para importar contactos | Editor | | `POST /api/filestorage/upload/livechat?botID=…&contactID=…&fileType=…` | Adjuntos en mensajes de chat | Agent | | `POST /api/filestorage/upload/plugin?botID=…&pluginID=…&fileType=…` | Archivo multimedia del encabezado de una plantilla de WhatsApp completada; `pluginID` es el `FilledWhatsAppTemplateID` | Agent | | `POST /api/filestorage/upload/widget?widgetID=…&fileType=Image` | El avatar del widget del sitio web | Editor | Todos están en `https://panel.chatfuel.com`. `fileType` es `Image`, `Video`, `Audio` o `Document`. Un parámetro opcional `extension` define la extensión del archivo sin punto, como `jpg` o `pdf`: ```bash curl -s "https://panel.chatfuel.com/api/filestorage/upload/bot?botID=$BOT_ID&fileType=Document&extension=csv" \ -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \ -F "file=@contacts.csv" ``` La respuesta describe el archivo guardado (aquí se omiten algunos campos): ```json { "id": "6f1c…", "type": "Document", "status": "Downloaded", "contentType": "text/csv", "size": 48213, "extension": "csv", "createdAt": "2026-10-06T10:15:00Z", "deleteAfter": "2026-10-06T12:15:00Z" } ``` Pasa `id` como `FileID`, por ejemplo a `csvContactImportCreate`, `goodsProductCreate` o `whatsappAttachmentMessageSend`. Un archivo que no se usa en dos horas, como indica `deleteAfter`, se elimina. ## Cómo leer un archivo [#cómo-leer-un-archivo] ```graphql type Query { # A file by ID: { id url type status size }. file(id: FileID!): File! } type Mutation { # Starts downloading a file that is stored with an external service, such as media a contact sent on a channel. fileStartDownload(id: FileID!): File! } ``` `status` indica si el archivo está listo: * `Downloaded`: `url` apunta al archivo. * `NotDownloaded`: el archivo sigue en el servicio externo. Llama a `fileStartDownload` y vuelve a leer el archivo más tarde. * `DownloadInProgress`: Chatfuel lo está descargando. * `Failed`: la descarga falló. * `Expired`: el archivo se eliminó tras su período de retención, o nunca existió. Guarda el ID del archivo en lugar de la URL, y vuelve a leer `url` cuando necesites el archivo. ## Cómo seguir una tarea [#cómo-seguir-una-tarea] Las operaciones que tardan devuelven una `Task` de inmediato y continúan en segundo plano: `csvContactExportStartBySegment`, `csvContactExportStartByIDsList` y `specialistStartGoogleCalendarSync`. Una tarea pertenece a su bot, y cualquier usuario virtual del bot puede leerla (**Agent**). ```graphql type Query { getTask(id: TaskID!): Task! } type Subscription { taskUpdated(id: TaskID!): Task! } ``` ```graphql query Export($taskID: TaskID!) { getTask(id: $taskID) { id completedPoints totalPoints deadline statuses { type startedAt } # Created, InProgress, Paused, Cancelled, Failed, Finished data { __typename ... on CSVContactsExport { file { url status } } } } } ``` `statuses` es el historial de la tarea; la última entrada es el estado actual. El progreso es `completedPoints` de `totalPoints`. Cuando una exportación de contactos llega a `Finished`, `data.file` es el CSV que debes descargar. Usa preferentemente la suscripción `taskUpdated` en lugar de consultar periódicamente; si consultas periódicamente, espera unos segundos entre llamadas. ## Problemas comunes [#problemas-comunes] ### La subida devuelve 400 [#la-subida-devuelve-400] Falta un parámetro de consulta obligatorio, como `botID`, `contactID`, `widgetID` o `fileType`, o tiene un valor incorrecto, o el cuerpo no es `multipart/form-data`. Envía el archivo como la primera parte del formulario, como hace `curl -F`. ### "FileDoesNotExist" al usar un archivo subido [#filedoesnotexist-al-usar-un-archivo-subido] El archivo se subió hace más de dos horas y nunca se usó, así que se eliminó. Vuelve a subirlo justo antes de la mutación que lo usa. ### Una tarea se queda en "InProgress" [#una-tarea-se-queda-en-inprogress] Las exportaciones y sincronizaciones grandes pueden tardar varios minutos. Revisa `completedPoints` para comprobar que avanza, y `deadline` para conocer la hora límite en la que se espera que termine la tarea.