Conversation.cs

namespace ACSforMCS
{
    /// <summary>
    /// Represents a DirectLine conversation session with a Bot Framework bot.
    /// This class encapsulates the response received from the DirectLine API when starting
    /// a new conversation and contains all the necessary information to establish
    /// real-time communication with the bot throughout the call duration.
    /// 
    /// The Conversation object is typically created when a new call is initiated and
    /// serves as the foundation for all subsequent bot interactions during that call.
    /// </summary>
    public class Conversation
    {
        /// <summary>
        /// Unique identifier for the DirectLine conversation session.
        /// 
        /// This ID is generated by the Bot Framework DirectLine service and is used to:
        /// - Send user messages to the specific conversation instance
        /// - Receive bot responses from the correct conversation thread
        /// - Maintain conversation state and context throughout the call
        /// - Associate the conversation with the corresponding ACS call in CallContext
        /// 
        /// The conversation ID remains active for the duration of the call and ensures
        /// that all interactions are properly scoped to the individual caller's session.
        /// </summary>
        public string? ConversationId { get; set; }

        /// <summary>
        /// Optional authentication token for the DirectLine conversation.
        /// 
        /// This token may be provided by DirectLine API for:
        /// - Enhanced security in token-based authentication scenarios
        /// - Time-limited access to the conversation
        /// - Scenarios where direct secret usage is not preferred
        /// 
        /// When present, this token can be used instead of the DirectLine secret
        /// for authenticating subsequent API calls to the conversation.
        /// The token typically has an expiration time and may need to be refreshed.
        /// </summary>
        public string? Token { get; set; }

        /// <summary>
        /// WebSocket URL for real-time streaming of bot activities and responses.
        /// 
        /// This URL enables bidirectional real-time communication with the bot and is used to:
        /// - Receive bot responses immediately as they are generated
        /// - Stream conversation activities without polling the REST API
        /// - Maintain low-latency communication for voice scenarios
        /// - Handle multiple activity types (messages, transfers, end-of-conversation signals)
        /// 
        /// The WebSocket connection established using this URL allows the CallAutomationService
        /// to listen for bot responses and process them in real-time, ensuring natural
        /// conversation flow during voice calls.
        /// </summary>
        public string? StreamUrl { get; set; }

        /// <summary>
        /// Optional reference to a grammar configuration for speech recognition optimization.
        /// 
        /// This identifier may be used for:
        /// - Custom speech recognition models tailored to specific domains or vocabularies
        /// - Enhanced accuracy for industry-specific terminology or phrases
        /// - Optimization of speech-to-text processing for the conversation context
        /// - Integration with specialized language models or recognition grammars
        /// 
        /// When specified, this grammar reference can help improve the accuracy of
        /// speech recognition by providing context-specific language models that
        /// better understand the expected vocabulary and speech patterns for the conversation.
        /// </summary>
        public string? ReferenceGrammarId { get; set; }
    }
}