Local File Integration

All file types are supported when the source is a local device like your computer or mobile phone

Upload from your local device

Uploading or "picking" a file from your local device in the context of Filestack means choosing a file and creating a distributable link to that file. In the context of uploading local files, they are uploaded either to your cloud storage, or Filestack's and then a link is returned. This is the Filestack URL that all "Pick" functions return.

Sample Upload Code
filepicker.pick( { mimetypes: ['*/*'], services:['COMPUTER'], }, function(Blob){ console.log(JSON.stringify(Blob)); } );

Understanding how local file uploads work with Filestack

When you perform a pick on a file from your computer or mobile device, that file gets uploaded and stored to Filestack's servers where it will be accessible online. However, if you have configured one of our many storage options, then Filestack will treat a simple pick as a pickAndStore and deposit that file into your personal cloud storage.

Smaller Files and Filestack

For the Filestack API, if the file that is being uploaded is less than 1mb and the source is a desktop, or the file is less than 200kb and the source is a mobile device, then Filestack is transferring the file data via a standard ajax post request to the Filestack REST API.

Larger Files and Multipart Uploads

If the file being uploaded is larger than 1mb and the source is a desktop, or the file is larger than 200kb and being uploaded from a mobile device, then Filestack utilizes a multipart upload method. The file is divided into 1mb chunks which are then uploaded in parallel (many chunks at the same time). Filestack creates a maximum of 1000 chunks, so for bigger files the chunks may be proportionately larger. If a specific chunk fails to upload, Filestack will retry uploading that chunk. It will attempt up to 10 retries. Filestack's multipart uploads are resilient and use a generous timeout limit before attempting to upload a chunk from the beginning. Once all of the file chunks have reached their destination, they are reassembled into a complete copy of the original file. Depending on the size of the file being uploaded, the reassembly process can take a significant chunk of time. This process often begins at around the 85% mark of the upload progress bar. If you are dealing with large files, we urge you to be patient. When measured against other uploading techniques and services, large files are uploaded up to 20% faster when uploaded using filestack.

Download to your local device

Exporting a file to your computer in the context of Filestack means saving a file from a url or Filestack Blob object to your local device.

Sample Export Code
filepicker.exportFile( 'https://www.filestackapi.com/api/file/qHi4LxRh28IeEBdJcFpw', { mimetype:'*/*', suggestedFilename: 'newFile', services: ['COMPUTER'] }, function(Blob){ console.log(Blob.url); } );

Sample Image Conversion Code for local files

If you have a Filestack Blob object or Filestack URL, then you can use the Filestack REST or Javascript APIs to convert office documents and image files. In the sample code below we "pick" an image file from your device and use the Javascript API convert method to resize the image to 400w by 400h in pixels.

Sample Conversion Code
filepicker.pick( { services: ['COMPUTER'], mimetype: 'image/*', }, function(pickedBlob){ console.log("Conversion in progress...") filepicker.convert( pickedBlob, { width: 400, height: 400, }, { location: 'S3' }, function(convertedBlob){ console.log("Converted file url: ", convertedBlob.url); console.log("File is stored under your S3: ", convertedBlob.key); filepicker.remove( pickedBlob, function(){ console.log("Removed"); } ); } ); } );

Combining Filestack Functions for local files

Now let's combine these methods and see what you can achieve with Filestack! Here we pick an image from your local device, crop and resize it, then save it back to your device.

Sample Multi-Function Code
filepicker.pick( { services: ['COMPUTER'], mimetype: 'image/*', }, function (Blob) { filepicker.convert( Blob, { width: 300, height: 300, crop_first: true }, function (converted_Blob) { filepicker.exportFile(converted_Blob.url, { services: ['COMPUTER'], mimetype: Blob.mimetype, suggestedFilename: 'converted_' + Blob.filename }, function (exported_Blob) { console.log('File successfully saved!'); }); }); });

Webhooks for Your Application

Webhooks serve the purpose of notifying users about events that occur in relation to their Filestack account. In your developer portal, you can set one or many urls whose purpose is to receive the messages triggered by specific Filestack events.

These are the three event types that will send messages to your webhook url(s) concerning local file uploads:

  • Local File Uploads
  • Local File Exports
  • Local File Conversions

Configuring Webhooks

Filestack Webhooks are configured in the developer portal under Credentials > Webhooks. If you enter your url and select "All", then one entry will be made for each type of Filestack Webhook Event, including the ones from your local device. To learn more about configuring and receiving webhooks please visit our main webhooks documentation page.

Receiving a Webhook Notification

Configuring your server to receive a new webhook is the same as creating any page on your website. If you are using Sinatra, add a new route with the desired URL. In PHP you could create a new .php file on your server. It doesn't need to be complicated. With webhooks, your server is the server receiving the request. You can even use an external service such as RequestBin as shown in the screenshot above.

Webhook data is sent as JSON in the request's body. The full event details are included and can be used directly. The "action" in the JSON is the type of Filestack event that happened, be it a file being uploaded, or simply the Filestack dialog opening.

Filestack will retry sending a webhook 3 times if the first attempt fails. The second attempt to deliver a webhook happens 5 minutes after the first attempt, the third attempt happens after 1 hour, and the final attempt to deliver a webhook happens 12 hours after the first attempt.

Note that for file uploads, both symlinks and files copied with pickAndStore, the "client" field shows the service used.

For conversions, the "provider" shows where the file resides. If the file was stored to Filestack's storage, the provider will be "internal", otherwise it could be "amazon" if the original was stored to S3, or one of the cloud drives Filestack connects to, such as "Facebook" if the link to the file was a symlink.

The following are examples of what the local file specific webhook messages include and look like:

  1. File Upload (symlink):

  2. {  
       "action":"fp.upload",
       "timestamp":1443444905,
       "id":100946,
       "text":{  
          "url":"https://www.filestackapi.com/api/file/WAunDTTqQfCNWwUUyf6n",
          "client":"amazon",
          "type":"image/jpeg",
          "filename":"1579337399020824.jpg",
          "size":139154
       }
    }

  3. File Upload (with store):

  4. {
       "action":"fp.upload",
       "timestamp":1443515345,
       "id":105258,
       "text":{
          "container":"kg_bucket",
          "url":"https://www.filestackapi.com/api/file/0CpUz9H4QfaX7LwwsgUf",
          "filename":"Cat_crying_Lolcat.jpg",
          "client":"amazon",
          "key":"EqACdfNRmylz2h1SSYwT_Cat_crying_Lolcat.jpg",
          "type":"image/jpeg",
          "size":205354
       }
    }

  5. File Export (save to):

  6. {
      "action": "fp.export",
      "timestamp": 1444257665, 
      "id": 142447, 
      "text":{
        "source": "https://www.filestackapi.com/api/file/qHi4LxRh28IeEBdJcFpw",
        "client": "amazon",
        "filename": "newFiletest.jpg",
        "created": "https://www.filestackapi.com/api/file/s40jJOQDGVr2T86cgOAe"
      }
    }
            

  7. File Conversion:

  8. {
       "action":"fp.converse",
       "timestamp":1435586806,
       "text":{
          "url":"https://www.filestackapi.com/api/file/uydUKAcTSsWB3g5HOsB4/convert?w=102",
          "link":{
             "writeable":true,
             "mimetype":"image/jpeg",
             "handle":"uydUKAcTSsWB3g5HOsB4",
             "url":"filepicker_upload_persist/pHSrbCRqSqeR1wh8USfY_1.jpeg",
             "created_at":"2015-06-29T13:31:02.204Z",
             "provider":"amazon",
             "app_id":7876,
             "filename":"1.jpeg",
             "mongo_id":null,
             "_metadata":null,
             "access_tokens":[
    
             ],
             "is_folder":false,
             "persist":false,
             "user_id":null,
             "id":31968,
             "size":"111175"
          }
       },
       "id":109
    }