Documentation

Get Conversations

Guide for getting conversations from a chatbot

Get Conversations API Guide

The Get Conversations API endpoint allows you to retrieve conversations from a specific chatbot. You can filter conversations based on various criteria, including the chatbot's ID, date range, and filtered sources.

Endpoint

GET https://www.chatbase.co/api/v1/get-conversations

Request Headers

The API request must include the following header:

  • Authorization: Bearer <Your-Secret-Key> - The secret key for authenticating the API request.

Request Parameters

  • chatbotId (string, required): The ID of the target chatbot from which you want to retrieve conversations (found in the chatbot settings).
  • filteredSources (string, optional): A comma-separated string of sources to be filtered for the chatbot's conversation. The sources can be any of the following:

    • "API,"
    • "Chatbase site,"
    • "Instagram,"
    • "Messenger,"
    • "Slack,"
    • "Unspecified,"
    • "WhatsApp,"
    • "Widget or Iframe"

  • startDate (string, optional): A string representing the start date of the range within which conversations are to be fetched. The date string is expected to be in the "Year-Month-Day" format (e.g 2023-07-10 not 2023-7-10)endDate (string, optional): A string representing the end date of the range within which conversations are to be fetched. The date string is expected to be in the "Year-Month-Day" format (e.g 2023-07-13 not 2023-7-13).
  • page (string, optional, default=1): A string representing the page number of the results, used for pagination.
  • size (string, optional, default=10, max=100): A string representing the number of results per page, also used for pagination.

Request Example

curl --request GET \
     --url 'https://www.chatbase.co/api/v1/get-conversations?chatbotId=<chatbot-id>startDate=2023-01-01&endDate=2023-12-12&page=1&size=20' \
     --header 'accept: application/json'
const options = {method: 'GET', headers: {accept: 'application/json'}};

fetch('https://www.chatbase.co/api/v1/get-conversations?chatbotId=<chatbot-id>startDate=2023-01-01&endDate=2023-12-12&page=1&size=20', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://www.chatbase.co/api/v1/get-conversations?chatbotId=<chatbot-id>startDate=2023-01-01&endDate=2023-12-12&page=1&size=20"

headers = {"accept": "application/json"}

response = requests.get(url, headers=headers)

print(response.text)

Response

  • 200: Returns an array data[] with conversations matching the provided filters. Each conversation object has the following structure:

    • id (string): The ID of the conversation.
    • created_at (string): The timestamp of when the conversation was created.
    • messages (array): An array containing message objects with role and content properties.
    • chatbot_id (string): The ID of the chatbot associated with the conversation.
    • customer (string): The customer or user identifier.
    • source (string): The source of the conversation.
  • 400: If the provided start or end dates are invalid.

  • 401: If the request is unauthorized.

  • 404: If the chatbot ID is invalid.

  • 500: If there is an internal server error.

Example Response

{
  "data": [
    {
      "id": "string",
      "created_at": "string",
      "messages": [
        {
          "role": "string",
          "content": "string"
        }
      ],
      "chatbot_id": "string",
      "customer": "string",
      "source": "string"
    }
  ]
}

The Get Conversations API endpoint provides a way to retrieve conversations from a chatbot based on specified filters. The response includes an array of conversations, each with its relevant details.