Referencia de la API de archivos y tareas

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

Las subidas van a un endpoint HTTP aparte como multipart/form-data, con el mismo encabezado Authorization: Bearer <token> que las solicitudes GraphQL:

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:

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 "[email protected]"

La respuesta describe el archivo guardado (aquí se omiten algunos campos):

{
  "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

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

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).

type Query {
  getTask(id: TaskID!): Task!
}

type Subscription {
  taskUpdated(id: TaskID!): Task!
}

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

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

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"

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.