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.