Getting Started

The Runtime API is designed for bots and integrations to handle messages, events, actions, and webhook requests at runtime. Each request made to this API is authenticated as either a bot or an integration. It can also be accessed externally by providing a bot or integration ID, though doing so effectively authenticates the request as a bot or integration.

All the endpoints of the Runtime API are located behind the chat base path (api.botpress.cloud/v1/chat/).

The Runtime API has many nuances that aren’t relevant to bot developers—because of this, we recommend only making your requests using the official Botpress TypeScript Client, which simplifies some of the API’s trickier aspects.

If you decide to interact with the Runtime API using another HTTP client, you may experience unintended behaviour or encounter issues.

Using the Official TypeScript Client

The official TypeScript client is available as an NPM package. You can install it using any of the following command:

npm install @botpress/client

pnpm install @botpress/client

yarn add @botpress/client

Once installed, you can import the client and use it in your TypeScript code:

This example uses dotenv to manage Botpress credentials. If you’d rather manage your credentials differently, just remove the import and define your token and bot ID however you like.

import dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

const main = async () => {
  const token = process.env.TOKEN
  const botId = process.env.BOT_ID

  const client = new Client({
    token,
    botId,
  })

  const { messages } = await client.listMessages({})
  console.log(messages)
}

void main()

Quotas/limits

The maximum payload size for the Runtime API is 1 MB.

Next Steps

Now that you’ve successfully made your first request, you can explore other API endpoints and concepts. Here are a few things you can do next: