Chat session management guide

fern/chat/non-streaming.mdx

@@ -10,9 +10,13 @@ Build a chat integration that receives complete responses after processing, perf
 
 **What You'll Build:**
 * Simple request-response chat patterns with immediate complete responses
-* Session-based conversations that maintain context across multiple chats
+* Context management using `previousChatId` for linked conversations
 * Basic integration with predictable response timing
 
+<Note>
+For comprehensive context management options including sessions, see **[Session management](/chat/session-management)**.
+</Note>
+
 ## Prerequisites
 
 * Completed [Chat quickstart](/chat/quickstart) tutorial
@@ -21,7 +25,7 @@ Build a chat integration that receives complete responses after processing, perf
 
 ## Scenario
 
-We'll build a help desk system for "TechFlow" that processes support messages through text chat and maintains conversation history using sessions.
+We'll build a help desk system for "TechFlow" that processes support messages through text chat and maintains conversation history using `previousChatId`.
 
 ---
 
@@ -101,103 +105,13 @@ We'll build a help desk system for "TechFlow" that processes support messages th
 
 ---
 
-## 2. Context Management with Sessions
-
-<Steps>
-  <Step title="Create a session for persistent context">
-    Sessions allow multiple chats to share the same conversation context:
-
-    ```bash title="Create Session"
-    curl -X POST https://api.vapi.ai/session \
-      -H "Authorization: Bearer YOUR_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "assistantId": "your-assistant-id"
-      }'
-    ```
-  </Step>
-  <Step title="Use the session across multiple chats">
-    Once you have a session ID, use it for related conversations:
-
-    ```bash title="First Message with Session"
-    curl -X POST https://api.vapi.ai/chat \
-      -H "Authorization: Bearer YOUR_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "sessionId": "session_abc123",
-        "input": "My account is locked and I can't access the dashboard"
-      }'
-    ```
-
-    ```bash title="Follow-up in Same Session"
-    curl -X POST https://api.vapi.ai/chat \
-      -H "Authorization: Bearer YOUR_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "sessionId": "session_abc123",
-        "input": "I tried the suggestions but still can't get in"
-      }'
-    ```
-  </Step>
-  <Step title="Implement session management in TypeScript">
-    Build a session-aware chat manager:
-
-    ```typescript title="session-manager.ts"
-    async function createChatSession(assistantId: string): Promise<string> {
-      const response = await fetch('https://api.vapi.ai/session', {
-        method: 'POST',
-        headers: {
-          'Authorization': 'Bearer YOUR_API_KEY',
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({ assistantId })
-      });
-
-      const session = await response.json();
-      return session.id;
-    }
-
-    async function sendSessionMessage(
-      sessionId: string, 
-      message: string
-    ): Promise<string> {
-      const response = await fetch('https://api.vapi.ai/chat', {
-        method: 'POST',
-        headers: {
-          'Authorization': 'Bearer YOUR_API_KEY',
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-          sessionId: sessionId,
-          input: message
-        })
-      });
-
-      const chat = await response.json();
-      return chat.output[0].content;
-    }
-
-    // Usage example
-    const sessionId = await createChatSession('your-assistant-id');
-
-    const response1 = await sendSessionMessage(sessionId, "I need help with billing");
-    console.log('Response 1:', response1);
-
-    const response2 = await sendSessionMessage(sessionId, "Can you explain the charges?");
-    console.log('Response 2:', response2); // Will remember the billing context
-    ```
-  </Step>
-</Steps>
-
----
-
-## 3. Using previousChatId for Context
+## 2. Context Management with previousChatId
 
 <Steps>
-  <Step title="Link chats without sessions">
-    Alternative to sessions - link chats directly:
+  <Step title="Link chats for conversation context">
+    Use `previousChatId` to maintain context across multiple chats:
 
-    ```typescript title="previous-chat-context.ts"
+    ```typescript title="conversation-chain.ts"
     async function createConversation() {
       let lastChatId: string | undefined;
 
@@ -237,7 +151,7 @@ We'll build a help desk system for "TechFlow" that processes support messages th
 
 ---
 
-## 4. Custom Assistant Configuration
+## 3. Custom Assistant Configuration
 
 <Steps>
   <Step title="Use inline assistant configuration">
@@ -319,6 +233,7 @@ Enhance your non-streaming chat system further:
 * **[Add streaming capabilities](/chat/streaming)** - Upgrade to real-time responses for better UX
 * **[OpenAI compatibility](/chat/openai-compatibility)** - Use familiar OpenAI SDK patterns  
 * **[Integrate tools](/tools)** - Enable your assistant to call external APIs and databases
+* **[Session management](/chat/session-management)** - Learn about advanced context management with sessions
 * **[Add voice capabilities](/calls/outbound-calling)** - Extend your text chat to voice interactions
 
 <Callout>

fern/chat/quickstart.mdx

@@ -273,6 +273,7 @@ Take your chat bot to the next level:
 
 * **[Streaming responses](/chat/streaming)** - Add real-time typing indicators and progressive responses
 * **[Non-streaming responses](/chat/non-streaming)** - Learn about sessions and complex conversation flows
+* **[Session management](/chat/session-management)** - Learn advanced context management with sessions and previousChatId
 * **[OpenAI compatibility](/chat/openai-compatibility)** - Integrate with existing OpenAI workflows
 
 <Callout>