The Chat API offers an HTTP API to chat with your bot. It allows you to integrate Botpress into a backend application (in contrast with Webchat, which allows you to integrate Botpress with your website).

The Chat API is only available via an integration built by Botpress. Because of this, all users, conversations and messages created using the Chat API belong to the Chat integration.

This means you can’t use the Chat API to fetch conversations that occur within other integrations, like WhatsApp or Webchat. For that, check out the Runtime API.

​
Installation

To use this API, make sure the Chat integration is installed to your bot. You can find the Chat integration here. Then, make sure your integration is enabled and configured.

​
Configuration

The Chat Integration has no required configuration — you can use it as-is. However, it does expose a few options:

  • Encryption Key: Used to verify incoming requests. If you set this field, you are then responsible for signing the x-user-key header yourself. Check out the Authentication section for more information.

  • Webhook URL: Called by the Chat API to notify you of chat-related events. The standard way of listening to Chat API events is by opening an SSE stream — if you set this field, you will receive events both on the SSE stream and on the webhook. Check out the Realtime section for more information.

  • Webhook Secret: Only used if you set a webhook URL. Included in requests sent to your webhook to ensure that requests made to your webhook are coming from the Chat API.

​
Getting Started

To use the Chat API:

  1. Find your webhook ID. You can find it in the Chat Integration’s configuration page:

The webhook ID is the string at the end of the Webhook URL. In this case, the webhook ID starts with 90 and ends with 51:

  1. Check if you can reach the API by sending a GET request on https://chat.botpress.cloud/$YOUR_WEBHOOK_ID/hello.

  2. Create a chat user (this is not the same as a user in your Botpress Dashboard) by calling the createUser operation.

This operation won’t be available if you are using manual authentication. Check out the Authentication section for more information.

  1. In the response’s body you will find a user key. Copy this key.

  2. Create a conversation with your bot by calling the createConversation operation. You will need to provide a user key to authenticate yourself.

  3. Send a message to your bot by calling the createMessage operation. You will need to provide:

    • A user key to authenticate yourself
    • A conversation ID to specify which conversation you are sending the message to
    • A message payload. For example, a simple text message has the following payload format: { "type": "text", "text": "hello bot" }.

  4. Wait for your bot to respond, then list messages on the conversation by calling the listMessages operation. You will need to provide:

    • A user key to authenticate yourself
    • A conversation ID to specify which conversation you are listing the messages from.

​
Authentication

All requests sent to the Chat Integration’s API are authenticated with a x-user-key header. There are two ways to get this user key:

  • You call the createUser operation and get the key in the response’s body. This operation is the only one that is not authenticated.
  • You can sign it yourself.

We refer to the second method as manual authentication. Use this method to ensure that only you can chat with your bot over the Chat API.

​
How to sign your requests manually

To sign your requests yourself, you must choose:

  • A user ID. This can be any valid string, as long as it’s not already taken by another user.
  1. An encryption key. This can be any valid string. You must set this key in the Chat integration’s configuration. This is so the integration knows that you are using manual authentication.

The x-user-key header is a JWT. Here’s how to sign it using the jsonwebtoken NodeJS library:

const jwt = require('jsonwebtoken')
const YOUR_USER_ID = '$YOUR_USER_ID'
const YOUR_ENCRYPTION_KEY = '$YOUR_ENCRYPTION_KEY'
const xUserKey = jwt.sign({ id: YOUR_USER_ID }, YOUR_ENCRYPTION_KEY, { algorithm: 'HS256' })

When handling an incoming request, the Chat Integration will detect that you are using manual authentication and will use your encryption key to verify the x-user-key JWT header. If the signature is invalid, the request will be rejected with an unauthorized status code.

By manually signing your requests, you ensure that nobody except you can chat with your bot over the Chat API.

​
Limitation to manual authentication

When using manual authentication, calling createUser will result in an error response. When needed, call getOrCreateUser instead.

​
Realtime

The Chat API offers two ways of listening to chat events in real time:

  1. Server-Sent Events, which is the standard way.
  2. Webhooks, or HTTP callback URLs.

​
Server-Sent Events

To listen to chat-related events on an SSE stream, you must call the listenConversation operation. This operation will open an SSE stream that you can listen to.

​
Official JavaScript Client

There is an official JavaScript client for the Chat API. It is by far the most convenient way to interact with the Chat API. We strongly recommend using it. You can find it here.

Features:

  • Strongly typed operation inputs and outputs.
  • Handled manual authentication if you pass an encryption key and user ID.
  • Uses an SSE client to listen to conversation events.