get-botpress-turn-responses

Test Botpress bots by sending messages and getting turn-by-turn responses with logs.

Note: Your bot must have the webchat integration installed.

Installation

npm install @bp-growth/get-botpress-turn-responses

Usage

import { getChatTurnResponses } from '@bp-growth/get-botpress-turn-responses';

const messages = [
  { type: 'text', payload: { text: 'Hello' } },
  { type: 'text', payload: { text: 'How are you?' } }
];

const result = await getChatTurnResponses(messages, {
  botId: 'your-bot-id',
  token: 'your-token',
  workspaceId: 'your-workspace-id',
  delayBetweenMessages: 1000 // Optional
});

console.log(result.messages); // All messages
console.log(result.logs);     // All logs

API

getChatTurnResponses(messages, options)

Sends messages to a bot and returns responses with logs.

Parameters

• messages: Array of message objects with type and payload
  • Messages use the types from @botpress/sdk (text, image, audio, video, file, etc.)
• options: Configuration object
  • botId: Botpress bot ID (required)
  • token: Botpress API token (required)
  • workspaceId: Botpress workspace ID (required)
  • delayBetweenMessages?: Delay in ms between messages (default: 1000)
  • pollInterval?: Polling interval in ms for logs (default: 500)
  • timeout?: Timeout in ms for turn completion (default: 30000)

Returns

• conversationId: ID of the created conversation
• userId: ID of the created user
• messages: Array of all messages in the conversation (user and bot)
• logs: Array of all logs from the conversation

Message Types

The library supports all message types from @botpress/sdk:

// Text message
{ type: 'text', payload: { text: 'Hello' } }

// Image message
{ type: 'image', payload: { imageUrl: 'https://example.com/image.jpg' } }

// Audio message
{ type: 'audio', payload: { audioUrl: 'https://example.com/audio.mp3' } }

// Video message  
{ type: 'video', payload: { videoUrl: 'https://example.com/video.mp4' } }

// File message
{ type: 'file', payload: { fileUrl: 'https://example.com/file.pdf' } }

// Card message
{ 
  type: 'card', 
  payload: { 
    title: 'Card Title',
    subtitle: 'Card subtitle',
    imageUrl: 'https://example.com/image.jpg',
    actions: []
  } 
}

// Carousel message
{
  type: 'carousel',
  payload: {
    items: [
      { title: 'Item 1', subtitle: 'Description', imageUrl: '...' },
      { title: 'Item 2', subtitle: 'Description', imageUrl: '...' }
    ]
  }
}

// And more...

Turn Completion Detection

The library monitors the bot's logs for "Billed Tokens:" to determine when a conversation turn is complete. This ensures that all bot responses are received before sending the next message.

Example

import { getChatTurnResponses } from '@bp-growth/get-botpress-turn-responses';

async function testBot() {
  const messages = [
    { type: 'text', payload: { text: 'Hello' } },
    { type: 'text', payload: { text: 'I want to buy a hoodie' } },
    { type: 'text', payload: { text: "What's the most expensive one?" } }
  ];

  try {
    const result = await getChatTurnResponses(messages, {
      botId: process.env.BOTPRESS_BOT_ID!,
      token: process.env.BOTPRESS_TOKEN!,
      workspaceId: process.env.BOTPRESS_WORKSPACE_ID!,
      delayBetweenMessages: 1500
    });

    // Process user and bot messages
    result.messages.forEach(msg => {
      if (msg.userId === result.userId) {
        console.log('User:', msg.payload);
      } else {
        console.log('Bot:', msg.payload);
      }
    });

    // Check turn completions in logs
    const turnCompletions = result.logs.filter(log => 
      log.message.includes('Billed Tokens:')
    );
    console.log('Turns completed:', turnCompletions.length);

  } catch (error) {
    console.error('Error:', error);
  }
}

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run in watch mode
pnpm dev

# Run tests
pnpm test

# Run example
pnpm example

# Type checking
pnpm type-check

# Linting
pnpm lint

# Format code
pnpm format

Requirements

• Node.js >= 18
• Botpress account with API access
• Bot ID, Personal Access Token, and Workspace ID from Botpress

License

MIT