Manage files

Getting the file’s metadata

To get the details of a file you can use the Get File API endpoint.

You can also use this endpoint to retrieve a new temporary pre-signed URL to download a file if the previous pre-signed URL has already expired.

Using the Botpress Client

import { Client } from '@botpress/client'

const client = new Client({
  token: process.env.BOTPRESS_PAT,
  botId: process.env.BOTPRESS_BOT_ID,
})

const file = await client.getFile({ id: "YOUR_FILE_ID" });

Listing existing files of a bot

To list all the files of a bot you can use the List Files API endpoint.

Using the Botpress Client

const res = await client.listFiles({})
const files = res.files

Filtering by tag values

If you need to filter files by tags, pass in the tags parameter, which is an object containing tags as key-value pairs. This will only return files that include all the tags (and corresponding values) that you specify.

Using the Botpress Client

const { files } = await client.listFiles({
  tags: {
    category: 'Sales',
  },
})

You can also pass in an array of strings as the tag’s value. This returns files that have that tag with any of the specified values:

Using the Botpress Client

const { files } = await client.listFiles({
  tags: {
    category: ['Sales', 'Marketing'],
  },
})

Advanced tag filtering

Instead of passing in the value of a tag, you can pass in an object with the exists, not or in properties to allow for more advanced filtering.

exists

Use the exists property to specify whether a tag should be present or absent on the returned files:

Using the Botpress Client

const { files } = await client.listFiles({
  tags: {
    integrationName: {
      exists: false
    }
  }
})

not

Use the not property to specify a value (or an array of values) to exclude for a given tag:

Using the Botpress Client

const { files } = await client.listFiles({
  tags: {
    integrationName: {
      not: 'webchat', // Could be a string or an array of strings
    },
  },
})

in

Use the in property to specify a value (or an array of values) to include for a given tag:

Using the Botpress Client

const { files } = await client.listFiles({
  tags: {
    integrationName: {
      in: ['webchat', 'whatsapp'], // Could be a string or an array of strings
    },
  },
})

Pagination

The List Files API endpoint will return by default the 20 most recent files your bot has. If you need to list older files you can use the nextToken property returned in the API response to retrieve the next page (if any) of files. The nextToken will be included for each page if there are files remaining to be listed.

For example:

let res = await client.listFiles({})
const files = res.files

// You can put this in a loop to retrieve all the files if needed
if (res.meta.nextToken) {
  res = await client.listFiles({ nextToken: res.meta.nextToken })
  files.push(...res.files)
}

Updating the file metadata

Only the tags and access policies of a file can be updated.

Here’s an example of how to update the access policies and tags of a file using the Botpress Client:

Using the Botpress Client

const response = await client.updateFileMetadata({
  id: 'file_01K86HD0D5T3HFCGBEKQJFNKAD',
  accessPolicies: ['integrations'], // This value will replace the existing access policies of the file.
  tags: {
    // This acts as a "patch" or partial update, so only the tags specified here will be updated, the rest will remain unchanged. If you need to delete an existing tag, you can set it to a `null` value.
    category: 'Support', // This tag will be updated.
    knowledgeBaseName: null, // This tag will be deleted.
    subcategory: 'Technical', // This tag will be added.
    // Any other tags not specified here will remain unchanged.
  },
})

const updatedFile = response.file

Updating file content

If you need to update the content of a file, you can create a new file with the updated content and then delete the old file. The file ID will change in this case.

Deleting a file

To delete a file you can use the “Delete File” API endpoint.

Using the Botpress Client

await client.deleteFile({ id: "YOUR_FILE_ID" })