←back to manuals

Conversation Flow

Stateless Conversation Completion

The stateless complete endpoint provides a powerful way to have complete conversation interactions without creating or managing persistent conversation records. This is ideal for one-off interactions, API integrations, or scenarios where you don't need to maintain conversation history in the platform.

Unlike the conversation-based complete endpoint, the stateless complete endpoint allows you to provide the entire conversation context in a single request, including all previous messages. This gives you complete control over conversation state and history management.

To use stateless conversation completion:

The messages array must contain at least one message and represents the full conversation history that the AI will use as context.

Configuration Options

The stateless complete endpoint supports extensive configuration:

Bot Configuration:

  • botId: ID of an existing bot to use (optional if providing backstory)
  • backstory: Custom instructions for the AI (optional if using botId)
  • model: Specific AI model to use (overrides bot default)
  • datasetId: Dataset to provide as knowledge base
  • skillsetId: Skillset to provide abilities
  • privacy: Enable privacy mode for PII handling
  • moderation: Enable content moderation

Message History:

  • messages: Array of message objects with type and text (required)
    • Each message must specify type (user, bot, context, activity)
    • Each message must include text content
    • Messages are processed in order to build conversation context

Attachments:

  • attachments: Array of attachment URLs to include in the conversation
    • Each attachment must specify a url field
    • Attachments are processed and included as context

Contact Association:

  • contactId: Associate the interaction with a specific contact
    • Can be an existing contact ID string
    • Can be a contact object with fingerprint for trusted contact creation

Advanced Stateless Features

Function Calling:

Enable the AI to call functions during the interaction:

Extensions (Trusted Sessions Only):

For trusted API sessions, you can provide inline extensions:

  • extensions.backstory: Additional instructions for this specific interaction
  • extensions.datasets: Inline dataset records as arrays of text and metadata
  • extensions.skillsets: Inline skillset definitions with abilities
  • extensions.features: Enable specific features for this interaction

Multi-Turn Conversations

The stateless endpoint excels at multi-turn conversations where you manage state externally:

In this example, you're providing the previous exchange as context, and the AI will generate a response considering the full conversation history. You would store this history in your own application and add the AI's response to it for the next turn.

Response Structure

The stateless complete endpoint returns streaming events similar to the stateful complete endpoint:

  • send_result: Confirmation of the user's message processing
  • Streaming tokens: The AI's response delivered incrementally
  • receive_result: The complete AI response with usage statistics
  • result: Final result with complete response and metadata

When to Use Stateless vs Stateful

Use Stateless Complete When:

  • You want complete control over conversation state and history
  • You're integrating with existing systems that maintain their own conversation storage
  • You need temporary or one-off AI interactions without persistence
  • You want to avoid managing conversation IDs and lifecycle
  • You have specific requirements for how conversation data is stored
  • You're building a custom conversation UI with your own state management

Use Stateful Complete When:

  • You want the platform to manage conversation history automatically
  • You need conversation persistence for later retrieval or analysis
  • You're building a traditional chat interface
  • You want to leverage platform features like conversation search and analytics
  • You need conversation metadata and timestamps managed automatically

Performance and Resource Considerations

The stateless complete endpoint:

  • Can handle conversations of any length (limited by message array size and token limits)
  • Processes all messages to build context each time (no cached state)
  • Uses streaming for real-time response delivery
  • Has the same 800-second maximum duration as stateful endpoints
  • Counts tokens and messages toward your usage limits

Integration Patterns

Pattern 1: External State Management

Store conversation history in your application's database and include it in each request. This works well for applications that already have sophisticated state management.

Pattern 2: Temporary Interactions

Use stateless complete for one-time interactions where you don't need to maintain history, such as form validation, content generation, or quick queries.

Pattern 3: Hybrid Approach

Use stateless complete for testing and development, then transition to stateful conversations in production for better performance and built-in history management.

Best Practices:

  • Keep message arrays manageable - very long conversations should be summarized or truncated
  • Include only the most recent and relevant messages for context
  • Use contact association to track interactions across multiple stateless requests
  • Implement proper error handling for streaming responses
  • Monitor token usage as stateless calls can be more token-intensive than stateful
  • Consider rate limits when making frequent stateless requests
  • Cache bot configuration (botId, backstory, etc.) to avoid redundant specifications

Important Notes:

  • Stateless complete requests do not create conversation records in the platform
  • All context must be provided in each request's messages array
  • The AI has no memory between stateless requests unless you provide previous messages
  • Attachments are processed for each request and count toward usage limits
  • Contact tracking can link multiple stateless interactions to the same user
conversationflowstatelessstateful