Skip to content

chatfuel-lab/wizard / content/modules/core/skill

references/files-tasks.md

View on GitHub
# Files & async tasks

## Files

`File` entity: `{ id: FileID!, url, type: Image|Video|Audio|Document, status, size }`.

- `status: Expired | NotDownloaded | DownloadInProgress | Downloaded | Failed`. **If `status == Expired`, do not request or use any other field** — the file no longer exists. `fileStartDownload(id)` asks the platform to (re)fetch a remote file's bytes; poll `file(id)` until `Downloaded`.
- GraphQL never accepts file bytes — **uploads are REST**, returning a `FileID` that you then pass into a mutation input:

| Endpoint (POST, multipart field `file`, `Authorization: Bearer <token>`) | Used for |
|---|---|
| `{base}/api/filestorage/upload/livechat?fileType=&botID=&contactID=` | chat attachments (the chatfuel-livechat skill) |
| `{base}/api/filestorage/upload/bot?fileType=&botID=` | CSV imports, catalog images, specialist avatars |
| `{base}/api/filestorage/upload/widget?fileType=&botID=` | widget avatar |
| `{base}/api/filestorage/upload/plugin?fileType=&botID=&pluginID=` | WhatsApp template header media |
| `{base}/api/filestorage/upload/useraccount?fileType=` | user profile pictures |

`fileType` is one of `Image | Video | Audio | Document`. Upload errors mirror the GraphQL codes: `FileTooBig`, `FileContentTypeNotSupported`.

Through the app's proxy these are the only five paths under `/api` that are forwarded, and three rules apply to them there: **`botID` is required** on the four bot-scoped ones (it is the only thing the proxy's fence can check, so an upload without it answers `400 InvalidRequest`), the method must be `POST` (anything else is `405`), and `useraccount` — which writes to the Chatfuel account behind the deployment's own token rather than to any caller's bot — is refused `403 AccountOperationBlocked` whenever the auth gate is on.

## Async tasks (`Task`)

Long-running jobs (CSV contact export, specialist Google-Calendar sync) return a `Task`:

```graphql
Task {
  id
  statuses { type startedAt }   # HISTORY, not a single value
  completedPoints
  totalPoints
  data { ... }                  # per-job payload, e.g. CSVContactsExport { file }
  deadline
}
```

Rules:

1. **`statuses` is a history** — the current status is the entry with the latest `startedAt` (`Created | InProgress | Paused | Cancelled | Failed | Finished`), not `statuses[0]`.
2. Progress is approximate: `completedPoints` can exceed `totalPoints`, and a task may finish before they converge. Render progress defensively.
3. **Past `deadline` ⇒ treat the task as failed/timed out** even without a `Failed` status.
4. Track via `getTask(id)` polling or the `taskUpdated(id)` subscription.
5. Cancellation lives in the owning domain, not on Task (e.g. `csvContactExportCancel`), and is async — wait for a `Cancelled` status.
6. `data` is an interface — always select `__typename` and the concrete type's fields (e.g. `... on CSVContactsExport { file { ... } }`). An `UnavailableTaskData` branch means no access.

## The three async patterns in this API

1. **Task-tracked**: mutation returns `Task` → `getTask` / `taskUpdated` (CSV export, GCal sync).
2. **Domain subscription**: mutation returns the entity or `Boolean`, completion arrives on a dedicated subscription (`csvContactImportUpdated`, `whatsAppBusinessPhoneNumberUpdated`, `metaAdsSyncStateUpdated`, `fbPagesSyncStatusUpdated`).
3. **Timestamp polling**: fire-and-forget mutation, then poll a `...LastUpdatedAt` field until it advances (WhatsApp business-entities refetch).

The mutation's return type in `references/schema.graphql` tells you which pattern applies: `Task` is pattern 1, the entity or `Boolean` is pattern 2 or 3 — look for a matching subscription first, and fall back to a `...LastUpdatedAt` field. The bundle carries no descriptions, so there is no doc-comment to confirm it from; the examples in this module show each pattern end to end.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall