Referência da API de arquivos e tarefas

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

Os uploads vão para um endpoint HTTP separado como multipart/form-data, com o mesmo cabeçalho Authorization: Bearer <token> das requisições GraphQL:

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:

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

A resposta descreve o arquivo armazenado (alguns campos foram omitidos aqui):

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

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

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

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 é 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

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

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"

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.