Compiled Bot Analytics

The Botpress Cloud dashboard provides you with an Analytics page with counters for the total number of users, new users, returning users, sessions and messages. It also shows a chart with the data and allows you to filter by date range.

While this interface is great for understanding reach and engagement in a glance, you may need the data in a third-party service. Luckily, you can use the Botpress API to export the analytics data to your own database or system. Let’s see how to do it.

Making a request to the API

Send a GET request to https://api.botpress.cloud/v1/admin/bots/<your-bot-id>/analytics adding the following header: Authorization: Bearer <your-personal-access-token>.

Note

You can find your personal access token in your Botpress Dashboard. Click your avatar and select “Personal Access Tokens”. Generate a new one and copy it.

This is how the request would look like using Axios in a JavaScript application:

const requestConfig = {
  headers: {
    Authorization: `Bearer ${process.env.BOTPRESS_PERSONAL_ACCESS_TOKEN}`,
  },
}

const getAnalytics = await axios.get(`https://api.botpress.cloud/v1/admin/${botId}/analytics`, requestConfig)

If you were to print the analytics (available at getAnalytics.data.records), the result would look like this:

[
  {
    "startDateTimeUtc": "2023-10-18T00:00:00.000Z",
    "endDateTimeUtc": "2023-10-30T20:00:00.000Z",
    "returningUsers": 14,
    "newUsers": 4,
    "sessions": 4,
    "messages": 146
  },
  {
    "startDateTimeUtc": "2023-09-01T03:00:00.000Z",
    "endDateTimeUtc": "2023-09-31T19:00:00.000Z",
    "returningUsers": 38,
    "newUsers": 16,
    "sessions": 25,
    "messages": 1943
  }
]

Note

It’s a list of records containing the start and end date of the period, the number of returning users, new users, sessions and messages. With this information you can create your own charts and dashboards in your internal systems or favorite BI tool.

If you need advanced analytics about user behavior and the paths they take when interacting with the bot, you can use the Hooks method to export the data in real-time to a third-party service like Mixpanel, Hotjar, Segment or Amplitude.