AI Voice & Host API Reference¶

Complete API reference for the AI module covering voice personas, host commentary, entitlements, and player context.

IVXAISessionManager¶

Central singleton for AI voice persona sessions and host commentary sessions.

Properties¶

Methods¶

Initialize¶

public void Initialize(string userId, string userName, string authToken = null, string language = null)

Initializes the AI session manager with player identity and optional auth.

Parameters: - userId - Player identifier - userName - Player display name - authToken - Bearer token for API auth (optional if using API key) - language - ISO 639-1 language code (optional, defaults to config value)

Example:

IVXAISessionManager.Instance.Initialize("player_123", "Alex", myBearerToken, "en");

SetAuthToken¶

public void SetAuthToken(string newToken)

Updates the bearer token after a backend refresh.

Parameters: - newToken - New bearer token string

GetPersonas¶

public void GetPersonas(Action<List<IVXAIPersona>> onSuccess, Action<string> onError = null)

Fetches the list of available AI personas from the backend.

Parameters: - onSuccess - Callback with persona list - onError - Error callback

Example:

IVXAISessionManager.Instance.GetPersonas(
    personas => { foreach (var p in personas) Debug.Log(p.DisplayName); },
    err => Debug.LogError(err));

StartVoiceSession¶

public void StartVoiceSession(string personaId, string topic = null, Action<IVXAICreateVoiceSessionResponse> onSuccess = null, Action<string> onError = null)

Starts a voice session with entitlement check. If access is denied, OnEntitlementRequired fires instead.

Parameters: - personaId - Persona identifier (e.g. "FortuneTeller") - topic - Conversation topic (optional) - onSuccess - Success callback with session response - onError - Error callback

Example:

IVXAISessionManager.Instance.StartVoiceSession("FortuneTeller", "career",
    resp => Debug.Log($"Session {resp.SessionId} started"),
    err => Debug.LogError(err));

StartVoiceSessionDirect¶

public void StartVoiceSessionDirect(string personaId, string topic = null)

Starts a voice session without the entitlement check. Use when your game manages access control separately.

Parameters: - personaId - Persona identifier - topic - Conversation topic (optional)

SendText¶

public void SendText(string text)

Sends a text message to the active voice session.

Parameters: - text - Message text

Example:

IVXAISessionManager.Instance.SendText("Tell me about my future.");

StartRecording¶

public void StartRecording()

Begins capturing audio from the microphone for the active voice session.

StopRecording¶

public void StopRecording()

Stops microphone recording and sends the captured audio automatically.

SendAudio¶

public void SendAudio(byte[] pcmBytes)

Sends raw PCM16 audio data to the active voice session.

Parameters: - pcmBytes - Raw PCM16 audio bytes

CommitAudio¶

public void CommitAudio()

Signals the end of a speech segment after SendAudio calls.

TriggerSpeech¶

public void TriggerSpeech(string text)

Forces the AI to speak specific text during a voice session.

Parameters: - text - Text for the AI to speak

StopAudio¶

public void StopAudio()

Immediately silences AI audio playback.

EndVoiceSession¶

public void EndVoiceSession(Action<IVXAISessionAnalytics> onComplete = null)

Ends the active voice session and returns analytics.

Parameters: - onComplete - Callback with session analytics (may be null on error)

Example:

IVXAISessionManager.Instance.EndVoiceSession(analytics =>
{
    if (analytics != null)
        Debug.Log($"Duration: {analytics.DurationSeconds}s");
});

StartHostSession¶

public void StartHostSession(IVXAICreateHostSessionRequest request, Action<IVXAICreateHostSessionResponse> onSuccess = null, Action<string> onError = null)

Creates an AI host commentary session for game events.

Parameters: - request - Host session configuration - onSuccess - Success callback with session response - onError - Error callback

Example:

var request = new IVXAICreateHostSessionRequest
{
    GameMode = "classic",
    PlayerCount = 4,
    PlayerNames = new[] { "Alex", "Jordan" },
    Topic = "Science",
    Difficulty = "medium",
    TotalQuestions = 10,
    TextOnlyMode = false
};
IVXAISessionManager.Instance.StartHostSession(request,
    resp => Debug.Log($"Host session: {resp.SessionId}"),
    err => Debug.LogError(err));

SendHostGameEvent¶

public void SendHostGameEvent(string eventType, string state, string data = null)

Notifies the AI host of a game state change to trigger contextual commentary.

Parameters: - eventType - Event type ("question_start", "round_end", "match_end", etc.) - state - State descriptor (e.g. "question_3_of_10") - data - Optional JSON payload with additional context

SubmitHostAnswer¶

public void SubmitHostAnswer(string playerId, int answerIndex)

Submits a player's answer to the host session for commentary.

Parameters: - playerId - Player identifier - answerIndex - Index of the selected answer

SendHostText¶

public void SendHostText(string playerId, string text)

Sends player chat text to the AI host.

Parameters: - playerId - Player identifier - text - Chat message text

TriggerHostSpeech¶

public void TriggerHostSpeech(string text)

Forces the AI host to speak specific text.

Parameters: - text - Text for the host to speak

EndHostSession¶

public void EndHostSession(Action onComplete = null)

Ends the active host session.

Parameters: - onComplete - Completion callback

Events¶

Voice Session Events¶

Host Session Events¶

IVXAIEntitlementManager¶

Manages access control, free trials, subscriptions, and IAP product queries. Created internally by IVXAISessionManager and accessible via the Entitlement property.

Properties¶

Methods¶

CheckAccess¶

public void CheckAccess(string personaId, Action<IVXAIEntitlementResponse> onResult, Action<string> onError = null)

Checks whether the player can access a specific persona.

Parameters: - personaId - Persona to check - onResult - Result callback with entitlement response - onError - Error callback

Example:

IVXAISessionManager.Instance.Entitlement.CheckAccess("FortuneTeller",
    resp => Debug.Log($"Can access: {resp.CanAccessPersona}"));

CanStartFreeSession¶

public bool CanStartFreeSession()

Returns whether a free session is available today.

Returns: true if free sessions remain

GetProducts¶

public void GetProducts(Action<List<IVXAIProductInfo>> onResult)

Fetches available IAP products for AI access.

Parameters: - onResult - Callback with product list

SubmitPurchase¶

public void SubmitPurchase(string productId, string receiptData, Action<IVXAIPurchaseResponse> onResult)

Validates an IAP receipt server-side and refreshes entitlements.

Parameters: - productId - Store product identifier - receiptData - Platform-specific receipt data - onResult - Result callback

Events¶

IVXAIConfig¶

ScriptableObject holding AI module configuration.

API Configuration¶

Session Settings¶

Audio Settings¶

Language¶

Free Trial¶

UI Hints¶

Data Models¶

IVXAIPersona¶

IVXAISessionAnalytics¶

IVXAIEntitlementResponse¶

IVXAIMessage¶

IVXAISocialProofData¶

IVXAIProductInfo¶

IVXAIPlayerContext¶

Methods¶

public void CalculatePersonalityHints()

Auto-detects personality flags (IsNewPlayer, IsVeteran, IsCompetitive, IsCasual, IsSpeedDemon, IsAccuracyFocused) from stats.

public string GetPersonalitySummary()

Returns a human-readable personality summary string.

IVXAICreateHostSessionRequest¶

IVXAIMatchContext¶

Methods¶

public string GenerateContextString()

Generates a formatted context string for the AI host session.

See Also¶

• AI Module Guide
• Core Module
• Monetization Module