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.

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' })

const result = await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const file = response.file

Listing existing files of a bot

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

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

const result = await fetch('https://api.botpress.cloud/v1/files', {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.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.

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

import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  category: 'Sales',
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files

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:

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

import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  category: ['Sales', 'Marketing'],
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files

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:

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

import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  integrationName: {
    exists: false,
  },
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files

`not`

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

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

import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  integrationName: {
    not: 'webchat', // Could be a string or an array of strings
  },
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files

`in`

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

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

import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  integrationName: {
    in: ['webchat', 'whatsapp'], // Could be a string or an array of strings
  },
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files

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:

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

await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
  method: 'PUT',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
  body: {
    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.
    },
  },
})

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.

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

await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
  method: 'DELETE',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})