Skip to main content

Conversations Overview

The Conversations API allows you to create, manage, and interact with conversation threads in the IndexSDK system. Conversations serve as the container for chat interactions between users and AI agents.

Architecture​

Conversations are domain-scoped entities that track chat interactions. Each conversation is associated with:

  • A domain (group_name) that identifies the tenant
  • A user_id that identifies the user
  • A conversation_id that uniquely identifies the conversation
  • A context object that stores user information and metadata
  • Messages exchanged within the conversation

Authentication Flow​

Before creating conversations, you must authenticate using the Client Credentials API to obtain an auth token. This token is then used to authenticate requests to conversation endpoints.

Key Concepts​

Conversation Creation​

When you create a conversation using sync-conversation:

  1. A new conversation is created with a unique conversation_id
  2. If a context is provided, it's stored with the conversation
  3. If a greeting message is configured for the domain, it's automatically created as the first message
  4. The greeting message can include personalized content based on user context (e.g., user's first name)

Conversation Context​

The context object allows you to store user information and metadata with the conversation:

  • User details (first_name, last_name, etc.)
  • Custom metadata
  • Session information

This context can be updated throughout the conversation lifecycle.

Conversation Deletion​

Conversations can be deleted by setting is_delete: true in the sync-conversation request along with the conversation_id.

Next Steps​