API Reference

Introduction

The Chat Integration offers an HTTP API to chat with your bot. It is often referred to as the Chat API even though it's really only an integration like any other. For the rest of this document, we may use both terms interchangeably.

Installation

To use this API, you must install the Chat Integration.

You can find it ➡️ here. ⬅️

Then, make sure to go to your bot configuration page, and enable the integration, by toggling it, and hitting "save".

Configuration

The Chat Integration has no required configuration. You can use it as is. But it does expose a few options:

  • Encryption Key: This key is entirely optional. If you are just starting with the Chat API, you should probably leave it empty. This key is used to verify incoming requests. If you set it, you are then responsible for signing the x-user-key header yourself. See the Authentication section for more information.

  • Webhook URL: This URL is entirely optional. If you are just starting with the Chat API, you should probably leave it empty. This URL will be called by the Chat API to notify you of chat-related events. It is optional because the standard way of listening to Chat API events is by opening an SSE stream. If you set this URL, you will receive events both on the SSE stream and on the webhook. See the Realtime section for more information.

  • Webhook Secret: This secret is only used if you set a webhook URL. It will be included in requests sent to your webhook so you ensure that requests made to your webhook are indeed coming from the Chat API.

Getting Started

Here's how 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 found in the webhook URL:
in this case, the webhook id start with **90** and ends with **51**

in this case, the webhook id start with 90 and ends with 51

  1. Check if you can reach the API by doing 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. See 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 and a message payload. A simple text message has the following payload format: { "type": "text", "text": "hello bot" }.
  4. Wait for your bot to respond and list messages on the conversation by calling the listMessages operation. You will need to provide a user key to authenticate yourself and 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:

  1. You call the createUser operation and get the key in the response's body. This operation is the only one that is not authenticated.
  2. 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 pick 2 things:

  1. A user ID. This user ID is of your choosing. It can be any valid string that is not yet used by another user.
  2. An encryption key. This key is also of your choosing. It can be any valid string. You must set this key in the Chat Integration's configuration. This way 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.

Important: When using manual authentication, you can no longer call the createUser operation and must call the getOrCreateUser operation instead. The first one is disabled to ensure only you can chat with your bot. Attempting to call the createUser operation will result in an error response.

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.