Downloading and Uploading Files

Downloading Files

Airtop allows your agents to download files from the web. This is useful for a variety of use cases such as downloading a PDF to analyze, or downloading an image to use in a design.

First, you’ll need to perform an action that will trigger a download. For example, you can use the Click action to click on a button that will trigger a download. Then, you can request that the file being downloaded be written to the local file system.

1
// Click on the button that will trigger a download
2
await client.windows.click(session.data.id, window.data.windowId, {
3
    elementDescription: "The button with the text 'Download PDF'",
4
});
5
6
// Download the next file in the queue
7
await client.sessions.downloadNextFile(session.data.id, "./test.pdf");

You can also specify a callback to get progress updates on the download.

1
await client.sessions.downloadNextFile(session.data.id, "./test.pdf", (downloaded, total) => {
2
    console.log(`Downloaded: ${downloaded} / ${total} bytes`);
3
});

Lookback

By default, downloadNextFile waits for a file to be downloaded, or looks back in time for the previous 5 seconds to see if a file download was triggered. This can be useful if the click interaction was very fast and triggered a download before the downloadNextFile call was made. However, you can configure the lookback period to be as long or short as you want, including 0 to disable lookback.

1
  await client.sessions.downloadNextFile(session.data.id, "./test.csv", {
2
    lookbackSeconds: 0,
3
  });

There are other options to further control the download process if you are downloading multiple files, or want to initiate the download process yourself at a later time.

Finer grained control of the download

Most of the time, you can use the downloadNextFile method to download the next file in the queue. However, if you need more control over the download, you can use other methods.

waitForDownload returns metadata about the file that allows you to manually download the file. The response includes a downloadUrl which is a 1 hour, signed URL that can be used to download the file from any HTTP client.

1
  await client.windows.click(session.data.id, window.data.windowId, {
2
    elementDescription: "The button with the text 'Download PDF' inside the 'Different MIME types' section",
3
  });
4
5
  const file = await client.sessions.waitForDownload(session.data.id);
6
  const response = await fetch(file.downloadUrl);
7
  ...

Alternatively, you can always list the files that have been downloaded so far for a single session.

1
const files = await client.files.list({
2
    sessionIds: [session.data.id],
3
});

This can be useful if you need to download multiple files from the same session in succession and later want to retrieve them.

1
for (const file of files.data.files ?? []) {
2
    await client.files.download(file.id, `./${file.fileName}`);
3
}

Uploading Files