Session management
Overview
Vapi provides two approaches for maintaining conversation context across multiple chat interactions.
Two Context Management Methods:
previousChatId
- Links individual chats in sequencesessionId
- Groups multiple chats under a persistent session
previousChatId
and sessionId
are mutually exclusive. You cannot use both in the same request.
Prerequisites
- Completed Chat quickstart tutorial
- Basic understanding of chat requests and responses
Method 1: Using previousChatId
Link chats together by referencing the ID of the previous chat.
Here’s a TypeScript implementation of the conversation chain:
Method 2: Using sessionId
Create a persistent session that groups multiple chats.
- Sessions expire automatically after 24 hours by default. After expiration, you’ll need to create a new session to continue conversations.
- Web chat widget and SMS conversations automatically manage session creation and expiration. You don’t need to manually create or manage sessions when using these channels.
Here’s a TypeScript implementation of the session manager:
When to use each approach
Use previousChatId
when:
- Dealing with simple back-and-forth conversations
- Looking for a minimal setup
Use sessionId
when:
- Building complex multi-step workflows
- Long-running conversations
- Error resilience needed
Sessions are tied to one assistant. You cannot specify assistantId
when using sessionId
.
Multi-Assistant Workflows
For workflows with multiple assistants, create separate sessions for each assistant.
Webhook Support
Sessions support the following webhook events through server messaging:
session.created
- Triggered when a new session is createdsession.updated
- Triggered when a session is updatedsession.deleted
- Triggered when a session is deleted
To receive these webhooks, go to your Assistant page in the Dashboard and navigate to “Server Messaging” and select the events you want to receive.
These webhooks are useful for tracking session lifecycle, managing session state in your own database, and triggering workflows based on session changes.
Next Steps
- Streaming responses - Add real-time responses to session-managed chats
- OpenAI compatibility - Use familiar OpenAI patterns with sessions
- Custom tools - Give assistants access to external APIs within sessions