Access the full chat history of a CustomGPT conversation via the CustomGPTs RAG APIs Python SDK implementation. In this guide, we’ll show you how to retrieve messages from a specific conversation session with your CustomGPT chatbot. This means you’ll be able to fetch both user messages and the bot’s responses, enabling you to display or analyze past interactions programmatically.
As a prerequisite, see Getting Started with CustomGPT.ai for New Developers to ensure you have the basics set up (API key, etc.).
Notebook Link: CustomGPT Cookbook – SDK_Retrieve_Messages_of_conversation.ipynb
Introduction
Hi there! In this guide, we’ll walk through how to retrieve messages for a conversation using the CustomGPT API in a Python environment. Each conversation (sometimes called a session) in CustomGPT has a unique ID (session ID). Within that conversation, there’s a sequence of messages alternating between the user and the AI assistant (the chatbot).
Being able to fetch this history is useful for:
- Displaying chat history on a custom interface (so users can scroll up to see previous Q&A).
- Logging or analysis of chatbot interactions (for example, to analyze how users are asking questions or to review bot answers for accuracy).
- Continuing a conversation in a different context – you might retrieve messages to feed them into another system or to resume later.
We’ll cover how to start a conversation via the API, send a few messages, and then retrieve the whole message list.
Prerequisites
- CustomGPT API Key – Your auth token.
- CustomGPT Python SDK installed – We’ll use customgpt-client.
- A project ID – You need a project (bot) to have a conversation with. Use an existing project ID or create a new project (with at least some content so it can answer).
- Python environment – e.g., Google Colab or Jupyter Notebook to run the code.
Step-by-Step Guide
Let’s break it down into steps:
- Set up the SDK and your project.
Install and import the SDK, and set the API key:
!pip install customgpt-client
from customgpt_client import CustomGPT
CustomGPT.api_key = "YOUR_API_TOKEN"Get API keys
To get your API key, there are two ways:
Method 1 – Via Agent
- Agent > All Agents.
- Select your agent and go to deploy, click on the API key section and create an API.
Method 2 – Via Profile section.
- Go to profile (top right corner of your screen)
- Click on My Profile
- You will see the screen something like this (below screenshot). Here you can click on “Create API key”, give it a name and copy the key.
Please save this secret key somewhere safe and accessible. For security reasons, You won’t be able to view it again through your CustomGPT.ai account. If you lose this secret key, you’ll need to generate a new one.
- Also, ensure you have a project_id for the bot you want to chat with. If you don’t have one, you can create a quick project:
# (Optional) create a new project for demonstration
project_name = "Conversation Demo Bot"
demo_project = CustomGPT.Project.create(project_name=project_name, sitemap_path="https://adorosario.github.io/small-sitemap.xml")
project_id = demo_project.parsed.data.id
print("Using project:", project_id)- Otherwise, set project_id = “your_existing_project_id”.
- Start a new conversation.
To retrieve messages, you need a conversation session. Let’s initiate a conversation:
conversation = CustomGPT.Conversation.create(project_id=project_id)
session_id = conversation.parsed.data.id
print("New conversation session ID:", session_id)- This creates a new conversation for the project and returns a session_id (conversation ID). Initially, it will have no messages yet (or maybe a system message internally, but not from user side). Now we have a conversation context to work with.
- Send some messages in the conversation.
Let’s simulate a user and bot exchange by sending a question and getting a response:
user_prompt = "Hello! Can you tell me about this project?"
response = CustomGPT.Conversation.send(project_id=project_id, session_id=session_id, prompt=user_prompt)
print("Bot response:", response.parsed.data.message)- Here, CustomGPT.Conversation.send sends the user prompt to that conversation and returns the bot’s answer. We print the answer message text (assuming response.parsed.data.message contains the chatbot’s reply text). We could send multiple messages; for now, let’s assume one QA pair for demonstration.
You might repeat sending another question to have a longer conversation:
followup_prompt = "What's the main topic covered in the source?"
response2 = CustomGPT.Conversation.send(project_id=project_id, session_id=session_id, prompt=followup_prompt)
print("Bot response to follow-up:", response2.parsed.data.message)- Now our conversation has at least two user messages and two bot messages.
- Retrieve all messages of the conversation.
Now the main part: getting the message history.
messages_response = CustomGPT.Conversation.messages(project_id=project_id, session_id=session_id)
all_messages = messages_response.parsed.data.messages- The method name might be Conversation.messages or similar (based on context, likely it fetches the conversation transcript). We then extract the list of message objects from the response. Each message object probably has fields like role (user or assistant), content (the text), possibly an id or timestamp.
- Display or iterate through the messages.
Let’s iterate and print them in order:
for msg in all_messages:
role = msg.role # e.g., "user" or "assistant"
content = msg.message or msg.content # depending on field name
print(f"{role.capitalize()}: {content}")- The output should show:
User: Hello! Can you tell me about this project?
Assistant: (bot's answer to greeting)
User: What's the main topic covered in the source?
Assistant: (bot's answer to follow-up)- And so on, for all messages in that conversation.
This confirms we successfully retrieved the conversation history from the API. - Use the messages data as needed.
You now have all_messages list with structured data. You can integrate this into a chat UI (e.g., render bubbles for each user and assistant message), log it to a file or database, or perform analysis. For instance, you could scan through all_messages to find if the bot used a citation link in its answers (if the content contains URLs or references).
That’s it! You’ve retrieved and displayed the conversation messages using the CustomGPT SDK.
FAQs
What is the difference between Conversation.send and Conversation.messages in the SDK?
Conversation.send is used to send a new user message (prompt) to the conversation and get the AI’s response. It’s essentially for interacting with the bot. On the other hand, Conversation.messages (or similarly named endpoint) is a call to retrieve the entire message history of the conversation up to that point. In some SDK designs, there might not be a separate Conversation.messages if send returns the whole history each time, but typically they separate it: one for sending new prompts, another for retrieving history.
Do I need to fetch messages after every send?
Not necessarily. If your goal is just to display the conversation as it happens, you already have each new message as you send/receive it. However, if you want to load a past conversation or get the full context at once (for instance, if your app was restarted and you only have the session ID saved), then you would use the messages endpoint to fetch everything. It’s also useful for exporting logs or debugging.
What information does each message object contain?
Typically, each message will have:
role: who sent it (“user” or “assistant” (bot), sometimes “system” for system messages if any).
content: the text of the message.
Possibly timestamp: when it was sent.
Possibly message_id: an ID for the message.
Possibly conversation_id: to which conversation it belongs (though you know that since you queried by conversation).
If the bot message has citations, the content may include those citations as part of text (e.g., URLs or reference numbers).
The exact structure can be confirmed by printing out all_messages or checking SDK docs.
How can I get the conversation ID (session_id) for an existing conversation?
The conversation ID is returned when you create or list conversations. If you have ongoing conversations, you can use CustomGPT.Conversation.list(project_id=…) to get all conversations for a project and find the one you want (for example, by creation time or other metadata). That would give you the session IDs. You could also store session IDs when you start conversations in your application. Once you have the session_id, you can retrieve messages as shown.
Related Posts
- SDK: Update and Delete a Conversation Using CustomGPT API – Developer Guide – Learn how to rename (update) or delete an existing conversation session via API. This is useful if you want to manage or clean up conversation history.
- SDK: Create a Bot by Sitemap Using CustomGPT API – Comprehensive Guide – If you followed our example by creating a project with a sitemap for the conversation, see this guide for more on creating bots with different sources.
- SDK: Get Project Stats Using CustomGPT API – While not directly about conversations, you might be interested in usage stats (like number of conversations, queries) for your project, which this guide covers.
Priyansh is Developer Relations Advocate who loves technology, writer about them, creates deeply researched content about them.
