--- title: "Referência da API de arquivos e tarefas" description: "Faça upload de arquivos, leia suas URLs e acompanhe tarefas longas, como exportações de contatos e sincronizações do Google Calendar, com getTask e taskUpdated." canonical_url: https://chatfuel.com/pt/docs/public-api/files-and-tasks markdown_url: https://chatfuel.com/pt/docs/public-api/files-and-tasks.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Referência da API de arquivos e tarefas Faça upload de arquivos, leia suas URLs e acompanhe tarefas longas, como exportações de contatos e sincronizações do Google Calendar, com getTask e taskUpdated. Arquivos e tarefas são os dois recursos auxiliares dos quais o restante da Public API do Chatfuel depende. Arquivos são imagens, vídeos, áudios e documentos: você faz o upload deles por HTTP e passa os IDs para as mutações, e lê os arquivos que os contatos enviaram pelas URLs deles. Tarefas representam processos demorados, como uma exportação de contatos em CSV ou uma sincronização do Google Calendar, que você inicia com uma mutação e acompanha até terminarem. ## Como fazer upload de um arquivo [#como-fazer-upload-de-um-arquivo] Os uploads vão para um endpoint HTTP separado como `multipart/form-data`, com o mesmo cabeçalho `Authorization: Bearer ` das requisições GraphQL: | Endpoint | Para que serve | Função mínima | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------- | | `POST /api/filestorage/upload/bot?botID=…&fileType=…` | Imagens e vídeos em fluxos, imagens do catálogo, fotos de especialistas, arquivos CSV para importação de contatos | Editor | | `POST /api/filestorage/upload/livechat?botID=…&contactID=…&fileType=…` | Anexos em mensagens de chat | Agent | | `POST /api/filestorage/upload/plugin?botID=…&pluginID=…&fileType=…` | Mídia do cabeçalho de um template do WhatsApp preenchido; `pluginID` é o `FilledWhatsAppTemplateID` | Agent | | `POST /api/filestorage/upload/widget?widgetID=…&fileType=Image` | O avatar do widget do site | Editor | Todos ficam em `https://panel.chatfuel.com`. `fileType` é `Image`, `Video`, `Audio` ou `Document`. Um parâmetro opcional `extension` define a extensão do arquivo sem o ponto, como `jpg` ou `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" ``` A resposta descreve o arquivo armazenado (alguns campos foram omitidos aqui): ```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" } ``` Passe `id` como `FileID`, por exemplo para `csvContactImportCreate`, `goodsProductCreate` ou `whatsappAttachmentMessageSend`. Um arquivo que não for usado em até duas horas, como mostra `deleteAfter`, é excluído. ## Como ler um arquivo [#como-ler-um-arquivo] ```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` informa se o arquivo está pronto: * `Downloaded`: `url` aponta para o arquivo. * `NotDownloaded`: o arquivo ainda está no serviço externo. Chame `fileStartDownload` e leia o arquivo novamente mais tarde. * `DownloadInProgress`: o Chatfuel está baixando o arquivo. * `Failed`: o download falhou. * `Expired`: o arquivo foi excluído após o período de retenção, ou nunca existiu. Armazene o ID do arquivo em vez da URL e leia `url` novamente quando precisar do arquivo. ## Como acompanhar uma tarefa [#como-acompanhar-uma-tarefa] Operações demoradas retornam uma `Task` imediatamente e continuam em segundo plano: `csvContactExportStartBySegment`, `csvContactExportStartByIDsList` e `specialistStartGoogleCalendarSync`. Uma tarefa pertence ao seu bot, e qualquer usuário virtual do bot pode lê-la (**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` é o histórico da tarefa; a última entrada é o status atual. O progresso é `completedPoints` de `totalPoints`. Quando uma exportação de contatos chega a `Finished`, `data.file` é o CSV para baixar. Prefira a assinatura `taskUpdated` a fazer polling; se fizer polling, espere alguns segundos entre as chamadas. ## Problemas comuns [#problemas-comuns] ### O upload retorna 400 [#o-upload-retorna-400] Um parâmetro de consulta obrigatório, como `botID`, `contactID`, `widgetID` ou `fileType`, está ausente ou incorreto, ou o corpo não é `multipart/form-data`. Envie o arquivo como a primeira parte do formulário, como faz o `curl -F`. ### "FileDoesNotExist" ao usar um arquivo enviado [#filedoesnotexist-ao-usar-um-arquivo-enviado] O arquivo foi enviado há mais de duas horas e nunca foi usado, então foi excluído. Faça o upload novamente logo antes da mutação que o usa. ### Uma tarefa fica parada em "InProgress" [#uma-tarefa-fica-parada-em-inprogress] Exportações e sincronizações grandes podem levar vários minutos. Confira `completedPoints` para ver se a tarefa está avançando, e `deadline` para saber o horário limite em que ela deve terminar.