Botpress Client

Standalone API client for Botpress Cloud

The @botpress/client package provides a standalone HTTP client for interacting with the Botpress Cloud API. Use it to manage bots, integrations, conversations, messages, and users from any Node.js or browser environment.

Installation

npm

npm install @botpress/client

yarn

yarn add @botpress/client

Initialization

import { Client } from '@botpress/client'

const client = new Client({
  apiUrl: 'https://api.botpress.cloud',
  token: process.env.BOTPRESS_TOKEN,
  workspaceId: process.env.BOTPRESS_WORKSPACE_ID,
  botId: process.env.BOTPRESS_BOT_ID
})

Configuration Options

apiUrl · string · default: "https://api.botpress.cloud"

Botpress API base URL.

token · string · required

Authentication token (Personal Access Token or Bot token).

workspaceId · string

Default workspace ID for operations.

botId · string

Default bot ID for operations.

integrationId · string

Default integration ID for operations.

Client Types

The client is exported from different modules:

Public Client

For bot and integration runtime:

import { Client } from '@botpress/client'

const client = new Client({
  token: botToken
})

Runtime Client

For internal runtime operations:

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

const runtimeClient = new Client({
  token: runtimeToken
})

Admin Client

For workspace and bot management:

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

const adminClient = new Client({
  token: personalAccessToken
})

Basic Usage

Create a Conversation

const { conversation } = await client.createConversation({
  integrationId: 'integration-id'
})

console.log('Conversation ID:', conversation.id)

Send a Message

const { message } = await client.createMessage({
  conversationId: conversation.id,
  userId: user.id,
  type: 'text',
  payload: {
    text: 'Hello, world!'
  }
})

console.log('Message ID:', message.id)

Get a User

const { user } = await client.getUser({
  id: 'user-id'
})

console.log('User:', user)

List Messages

const { messages, meta } = await client.listMessages({
  conversationId: conversation.id,
  limit: 50
})

console.log('Messages:', messages.length)
if (meta.nextToken) {
  // Fetch next page
}

Operations

The client provides methods for:

Conversations

• createConversation() - Create a conversation
• getConversation() - Get conversation by ID
• listConversations() - List conversations
• updateConversation() - Update conversation
• deleteConversation() - Delete conversation
• getOrCreateConversation() - Get or create conversation

Messages

• createMessage() - Send a message
• getMessage() - Get message by ID
• listMessages() - List messages
• updateMessage() - Update message
• deleteMessage() - Delete message
• getOrCreateMessage() - Get or create message

Users

• createUser() - Create a user
• getUser() - Get user by ID
• listUsers() - List users
• updateUser() - Update user
• deleteUser() - Delete user
• getOrCreateUser() - Get or create user

Events

• createEvent() - Create an event
• getEvent() - Get event by ID
• listEvents() - List events

State

• getState() - Get state
• setState() - Set state
• getOrSetState() - Get or set state
• patchState() - Partially update state

Actions

• callAction() - Execute an integration action

Files

• uploadFile() - Upload a file
• getFile() - Get file metadata
• listFiles() - List files
• deleteFile() - Delete a file
• upsertFile() - Create or update file
• updateFileMetadata() - Update file metadata
• searchFiles() - Search files

Tables

• createTableRows() - Insert rows
• getTableRow() - Get a row
• findTableRows() - Query rows
• updateTableRows() - Update rows
• upsertTableRows() - Insert or update rows
• deleteTableRows() - Delete rows

Workflows

• createWorkflow() - Create workflow
• getWorkflow() - Get workflow
• updateWorkflow() - Update workflow
• deleteWorkflow() - Delete workflow
• listWorkflows() - List workflows
• getOrCreateWorkflow() - Get or create workflow

Participants

• addParticipant() - Add participant to conversation
• getParticipant() - Get participant
• listParticipants() - List participants
• removeParticipant() - Remove participant

Analytics

• trackAnalytics() - Track analytics events

Error Handling

import { isApiError, RuntimeError } from '@botpress/client'

try {
  const { user } = await client.getUser({ id: 'user-id' })
} catch (error) {
  if (isApiError(error)) {
    console.error('API Error:', error.code, error.message)
    console.error('Status:', error.status)
  } else {
    console.error('Unexpected error:', error)
  }
}

Error Types

isApiError · function

Type guard for API errors.

if (isApiError(error)) {
  // error.code, error.message, error.status
}

RuntimeError · class

SDK runtime error class.

throw new RuntimeError('Operation failed', cause)

Pagination

Many list operations support pagination:

let nextToken: string | undefined
const allMessages = []

do {
  const { messages, meta } = await client.listMessages({
    conversationId: conversation.id,
    limit: 100,
    nextToken
  })
  
  allMessages.push(...messages)
  nextToken = meta.nextToken
} while (nextToken)

console.log('Total messages:', allMessages.length)

Timeouts and Retries

The client uses axios with retry logic:

import { Client, axios, axiosRetry } from '@botpress/client'

const client = new Client({
  token: process.env.BOTPRESS_TOKEN
})

// Configure retries (done automatically by default)
axiosRetry(axios, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay
})

Environment Variables

.env

BOTPRESS_API_URL=https://api.botpress.cloud
BOTPRESS_TOKEN=bp_pat_your_token_here
BOTPRESS_WORKSPACE_ID=your_workspace_id
BOTPRESS_BOT_ID=your_bot_id

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

config()

const client = new Client({
  apiUrl: process.env.BOTPRESS_API_URL,
  token: process.env.BOTPRESS_TOKEN!,
  workspaceId: process.env.BOTPRESS_WORKSPACE_ID,
  botId: process.env.BOTPRESS_BOT_ID
})

See Also

• Authentication - API authentication methods
• Client Methods - Complete method reference
• BotSpecificClient - Type-safe bot client
• IntegrationSpecificClient - Type-safe integration client