@botpress/chat

Chat Client

Installation

npm install @botpress/chat # for npm
yarn add @botpress/chat # for yarn
pnpm add @botpress/chat # for pnpm

Usage

API Queries

The @botpress/chat package exports a Client class that can be used to interact with the Botpress Chat API. Here's a basic example:

import { Client } from '@botpress/chat'

const main = async () => {
  /**
   * You can find your webhook id in the the Botpress Dashboard.
   * Navigate to your bot's Chat Integration configuration. Look for:
   * https://webhook.botpress.cloud/$YOUR_WEBHOOK_ID
   */
  const webhookId = process.env.WEBHOOK_ID
  if (!webhookId) {
    throw new Error('WEBHOOK_ID is required')
  }

  const client = new Client({
    apiUrl: `https://chat.botpress.cloud/${webhookId}`,
  })

  // 0. create a chat user
  const { user, key: xChatKey } = await client.createUser({})

  // 1. create a conversation
  const { conversation } = await client.createConversation({ xChatKey, participants: [user.id] })

  // 2. send a message
  const { message } = await client.createMessage({
    xChatKey,
    conversationId: conversation.id,
    payload: {
      type: 'text',
      text: 'hello world',
    },
  })
  console.log('message', message)

  // 3. sleep for a bit
  await new Promise((resolve) => setTimeout(resolve, 2000))

  // 4. list messages
  const { messages } = await client.listMessages({
    xChatKey,
    conversationId: conversation.id,
  })

  console.log('messages', messages)
}

void main()
  .then(() => {
    console.log('done')
    process.exit(0)
  })
  .catch((err) => {
    console.error(err)
    process.exit(1)
  })

Realtime Events

You can also listen for messages and events in real-time:

// ...

const listener = await client.listenConversation({ id: conversation.id, xChatKey })

listener.on('message_created', (ev) => {
  if (ev.userId === user.id) {
    // message created by my current user, ignoring...
    return
  }
  console.log('message received >>>', ev)
})

Reconnection

The Client class does not automatically reconnect to the server if the connection is lost. This allow's you to handle reconnection in a way that makes sense for your application. To be notified when the connection is lost, you can listen for the error event:

// ...

const state = { messages }

const onDisconnection = async () => {
  try {
    await listener.connect()
    const { messages } = await client.listMessages({ xChatKey, conversationId: conversation.id })
    state.messages = messages
  } catch (thrown) {
    console.error('failed to reconnect, retrying...', thrown)
    setTimeout(onDisconnection, 1000) // consider using a backoff strategy
  }
}

listener.on('error', (err) => {
  console.error('connection lost', err)
  void onDisconnection()
})