Maintaining Conversation History

Learn how to maintain conversation history and context across sessions using NavTalk Real-time Digital Human API

Maintaining Conversation History Across Sessions

NavTalk supports maintaining conversation history across multiple sessions, allowing the digital human to remember previous conversations and maintain context continuity.

Workflow Overview

The conversation history workflow follows this sequence:

1. Store messages: Save user and assistant messages as they occur during the conversation
2. Send configuration: When WebSocket connection opens, send realtime.input_config message with voice, prompt, and optionally tools (for OpenAI models only)
3. Load on connection: Wait for realtime.session.created event
4. Send history: Send stored user messages using conversation.item.create messages
5. Wait for ready: After sending history, wait for realtime.session.updated event before starting audio input

Session configuration (voice, prompt, tools) is sent via realtime.input_config message immediately after the WebSocket connection opens. The conversation.item.create messages are only used to send conversation history after receiving realtime.session.created.

The tools parameter is optional and only applicable when using OpenAI models (gpt-realtime, gpt-realtime-mini). Function calling is not supported by other AI models.

Follow these steps to implement persistent conversation history:

1. Store Conversation History

   Save each conversation message to persistent storage as it occurs:

   JavaScript

   const NavTalkMessageType = Object.freeze({
       REALTIME_SESSION_CREATED: "realtime.session.created",
       REALTIME_SESSION_UPDATED: "realtime.session.updated",
       REALTIME_CONVERSATION_ITEM_COMPLETED: "realtime.conversation.item.input_audio_transcription.completed",
       REALTIME_RESPONSE_AUDIO_TRANSCRIPT_DONE: "realtime.response.audio_transcript.done",
       // ... other event types
   });
   
   // Save conversation history to localStorage
   async function appendRealtimeChatHistory(role, content) {
     // Get existing history from storage
     let history = localStorage.getItem("realtimeChatHistory");
     let realtimeChatHistory = history ? JSON.parse(history) : [];
     
     // Add new message
     realtimeChatHistory.push({ role, content });
     
     // Save back to storage
     localStorage.setItem("realtimeChatHistory", JSON.stringify(realtimeChatHistory));
   }
   
   // Call this function when receiving user transcription
   socket.onmessage = async (event) => {
     if (typeof event.data === 'string') {
       const data = JSON.parse(event.data);
       const nav_data = data.data;
       
       // Save user message when transcription completes
       if (nav_data && data.type === NavTalkMessageType.REALTIME_CONVERSATION_ITEM_COMPLETED) {
         const transcript = nav_data.content;
         if (transcript) {
           await appendRealtimeChatHistory("user", transcript);
         }
       }
       
       // Save AI response when complete
       if (nav_data && data.type === NavTalkMessageType.REALTIME_RESPONSE_AUDIO_TRANSCRIPT_DONE) {
         const transcript = nav_data.content;
         if (transcript) {
           await appendRealtimeChatHistory("assistant", transcript);
         }
       }
     }
   };
   

   import json
   import os
   
   NAV_TALK_MESSAGE_TYPE = {
       'REALTIME_SESSION_CREATED': 'realtime.session.created',
       'REALTIME_SESSION_UPDATED': 'realtime.session.updated',
       'REALTIME_CONVERSATION_ITEM_COMPLETED': 'realtime.conversation.item.input_audio_transcription.completed',
       'REALTIME_RESPONSE_AUDIO_TRANSCRIPT_DONE': 'realtime.response.audio_transcript.done',
       # ... other event types
   }
   
   def save_conversation_history(role, content, history_file="conversation_history.json"):
       """Save conversation message to file"""
       # Load existing history
       if os.path.exists(history_file):
           with open(history_file, 'r', encoding='utf-8') as f:
               history = json.load(f)
       else:
           history = []
       
       # Add new message
       history.append({"role": role, "content": content})
       
       # Save back to file
       with open(history_file, 'w', encoding='utf-8') as f:
           json.dump(history, f, ensure_ascii=False, indent=2)
   
   # Call when receiving messages
   async def handle_messages(websocket):
       async for message in websocket:
           if isinstance(message, str):
               data = json.loads(message)
               nav_data = data.get('data')
               
               if nav_data and data.get('type') == NAV_TALK_MESSAGE_TYPE['REALTIME_CONVERSATION_ITEM_COMPLETED']:
                   transcript = nav_data.get('content')
                   if transcript:
                       save_conversation_history("user", transcript)
               
               elif nav_data and data.get('type') == NAV_TALK_MESSAGE_TYPE['REALTIME_RESPONSE_AUDIO_TRANSCRIPT_DONE']:
                   transcript = nav_data.get('content')
                   if transcript:
                       save_conversation_history("assistant", transcript)
   
2. Load History on Session Start

   When establishing a new WebSocket connection, load the stored history and send it to the server:

   JavaScript

   async function sendSessionUpdate() {
     // Load conversation history from storage
     const history = localStorage.getItem("realtimeChatHistory");
     const conversationHistory = history ? JSON.parse(history) : [];
     
     // Session configuration (voice, prompt, tools, etc.) is sent via realtime.input_config
     // Only send user message history
     conversationHistory.forEach((msg) => {
       if (msg.role === "user") {
         const messageConfig = {
           type: "conversation.item.create",
           item: {
             type: "message",
             role: "user",
             content: [
               {
                 type: "input_text",
                 text: msg.content
               }
             ]
           }
         };
         
         try {
           // Send user messages from history
           socket.send(JSON.stringify(messageConfig));
           console.log("Sent historical message:", msg.content);
         } catch (e) {
           console.error("Error sending historical message:", e);
         }
       }
     });
   }
   
   // Call this after receiving session.created
   socket.onmessage = async (event) => {
     if (typeof event.data === 'string') {
       const data = JSON.parse(event.data);
       
       if (data.type === NavTalkMessageType.REALTIME_SESSION_CREATED) {
         console.log("Session created, sending history.");
         await sendSessionUpdate();
       }
       
       if (data.type === NavTalkMessageType.REALTIME_SESSION_UPDATED) {
         console.log("Session updated. Ready to receive audio.");
         // Start recording audio here
       }
     }
   };
   

   import json
   
   async def send_session_update(websocket):
       """Send conversation history after session configuration has been sent via realtime.input_config."""
       # Load conversation history
       history_file = "conversation_history.json"
       if os.path.exists(history_file):
           with open(history_file, 'r', encoding='utf-8') as f:
               conversation_history = json.load(f)
       else:
           conversation_history = []
       
       # Session configuration (voice, prompt, tools, etc.) is sent via realtime.input_config
       # Only send user message history
       for msg in conversation_history:
           if msg["role"] == "user":
               message_config = {
                   "type": "conversation.item.create",
                   "item": {
                       "type": "message",
                       "role": "user",
                       "content": [
                           {
                               "type": "input_text",
                               "text": msg["content"]
                           }
                       ]
                   }
               }
               try:
                   await websocket.send(json.dumps(message_config))
                   print(f"Sent historical message: {msg['content']}")
               except Exception as e:
                   print(f"Error sending historical message: {e}")
   
   # Handle session creation
   async def handle_messages(websocket):
       async for message in websocket:
           if isinstance(message, str):
               data = json.loads(message)
               
               if data.get('type') == NAV_TALK_MESSAGE_TYPE['REALTIME_SESSION_CREATED']:
                   await send_session_update(websocket)
               
               elif data.get('type') == NAV_TALK_MESSAGE_TYPE['REALTIME_SESSION_UPDATED']:
                   print("Session updated. Ready to receive audio.")
   
3. Restore Conversation Display

   When the page loads, restore the conversation history display for the user:

   JavaScript

   // Restore conversation history display on page load
   async function initConversationHistory() {
     // Load history from storage
     const historyStr = localStorage.getItem("realtimeChatHistory");
     const realtimeChatHistory = historyStr ? JSON.parse(historyStr) : [];
     
     // Render each historical message in the UI
     if (realtimeChatHistory && realtimeChatHistory.length > 0) {
       realtimeChatHistory.forEach(item => {
         appendMessageToUI(item.role, item.content);
       });
       
       // Scroll to bottom to show latest messages
       const chatContainer = document.querySelector('.chat-container');
       if (chatContainer) {
         chatContainer.scrollTop = chatContainer.scrollHeight;
       }
     }
   }
   
   function appendMessageToUI(role, content) {
     const container = document.createElement('div');
     container.classList.add('message', role === 'user' ? 'message-user' : 'message-assistant');
     
     const contentDiv = document.createElement('div');
     contentDiv.classList.add('message-content');
     contentDiv.textContent = content;
     
     container.appendChild(contentDiv);
     
     const chatContainer = document.querySelector('.chat-container');
     if (chatContainer) {
       chatContainer.appendChild(container);
     }
   }
   
   // Initialize on page load
   document.addEventListener('DOMContentLoaded', () => {
     initConversationHistory();
   });
   

   # For Python web applications, restore history when rendering the page
   def load_conversation_history():
       """Load and return conversation history"""
       history_file = "conversation_history.json"
       if os.path.exists(history_file):
           with open(history_file, 'r', encoding='utf-8') as f:
               return json.load(f)
       return []
   
   # In your web framework (Flask/Django/FastAPI), pass history to template
   @app.route('/')
   def index():
       history = load_conversation_history()
       return render_template('index.html', conversation_history=history)
   

Important Notes

When sending historical messages via conversation.item.create, only user messages can be sent. AI-generated historical messages cannot be embedded this way.