VoxtaClient

The VoxtaClient is the primary interface for interacting with the Voxta platform. It manages the SignalR connection lifecycle and provides an event-driven API for chat interactions.

High-level client for interacting with the Voxta conversational AI platform.

Attributes

running property

running: bool

Check if the client is currently connected and running.

Functions

Connection Lifecycle

These methods handle the connection to the Voxta server.

High-level client for interacting with the Voxta conversational AI platform.

Functions

negotiate

negotiate()

Perform the initial SignalR HTTP negotiation.

connect async

connect(connection_token: str, cookies: Optional[dict[str, str]] = None)

Establish the SignalR connection and authenticate.

Parameters:

• connection_token (str) –

  The SignalR connection token obtained from negotiation.

• cookies (Optional[dict[str, str]], default: None ) –

  Optional cookies to include in the connection request.

close async

close()

Close the client connection.

Session Management

Manage active chat sessions and character participants.

High-level client for interacting with the Voxta conversational AI platform.

Functions

start_chat async

start_chat(character_id: str, contexts: Optional[list[dict[str, Any]]] = None)

Start a new chat session with a specific character.

Parameters:

• character_id (str) –

  The ID of the character to chat with.

• contexts (Optional[list[dict[str, Any]]], default: None ) –

  Optional list of context objects to initialize the chat.

resume_chat async

resume_chat(chat_id: str)

Resume an existing chat session.

Parameters:

• chat_id (str) –

  The ID of the chat to resume.

stop_chat async

stop_chat(chat_id: str)

Stop an active chat session.

Parameters:

• chat_id (str) –

  The ID of the chat to stop.

subscribe_to_chat async

subscribe_to_chat(session_id: str, chat_id: str)

Subscribe to events for a specific chat session.

Parameters:

• session_id (str) –

  The session ID.

• chat_id (str) –

  The chat ID.

add_chat_participant async

add_chat_participant(character_id: str, session_id: Optional[str] = None)

Add a character as a participant to the current chat session.

Parameters:

• character_id (str) –

  The ID of the character to add.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

remove_chat_participant async

remove_chat_participant(character_id: str, session_id: Optional[str] = None)

Remove a character from the current chat session.

Parameters:

• character_id (str) –

  The ID of the character to remove.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

Interaction

Methods for sending messages and controlling the AI's response flow.

High-level client for interacting with the Voxta conversational AI platform.

Functions

send_message async

send_message(text: str, session_id: Optional[str] = None, do_reply: bool = True, do_user_inference: bool = True, do_character_inference: bool = True)

Send a user message to the session.

Parameters:

• text (str) –

  The message text.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

• do_reply (bool, default: True ) –

  Whether the AI should generate a reply immediately.

• do_user_inference (bool, default: True ) –

  Whether to perform action inference on the user message.

• do_character_inference (bool, default: True ) –

  Whether to perform action inference for the character response.

update_message async

update_message(message_id: str, text: str, session_id: Optional[str] = None)

Update the text of a previous message.

Parameters:

• message_id (str) –

  The ID of the message to update.

• text (str) –

  The new text for the message.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

delete_message async

delete_message(message_id: str, session_id: Optional[str] = None)

Delete a message from the session history.

Parameters:

• message_id (str) –

  The ID of the message to delete.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

trigger_action async

trigger_action(action: str, arguments: Optional[dict[str, Any]] = None, session_id: Optional[str] = None)

Explicitly triggers an AI action/response.

Parameters:

• action (str) –

  The name of the action to trigger.

• arguments (Optional[dict[str, Any]], default: None ) –

  Optional dictionary of arguments for the action.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

interrupt async

interrupt(session_id: Optional[str] = None)

Interrupt the current AI response/speech.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

retry async

retry(session_id: Optional[str] = None)

Retry the last AI response generation.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

revert async

revert(session_id: Optional[str] = None)

Revert the last message in the session.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

pause async

pause(session_id: Optional[str] = None, pause: bool = True)

Pause automatic continuation of the chat.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

• pause (bool, default: True ) –

  Whether to pause or resume.

UI & Presence

Handle typing indicators and status updates.

High-level client for interacting with the Voxta conversational AI platform.

Functions

typing_start async

typing_start(session_id: Optional[str] = None)

Notify the server that the user has started typing.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

typing_end async

typing_end(session_id: Optional[str] = None)

Notify the server that the user has stopped typing.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

request_suggestions async

request_suggestions(session_id: Optional[str] = None)

Request message suggestions from the AI.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

character_speech_request async

character_speech_request(character_id: str, session_id: Optional[str] = None, text: str = '')

Request the character to start/resume speaking.

Parameters:

• character_id (str) –

  The ID of the character.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

• text (str, default: '' ) –

  Optional specific text to speak.

speech_playback_start async

speech_playback_start(session_id: Optional[str] = None, message_id: Optional[str] = None)

Notify the server that speech playback has started for a message.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

• message_id (Optional[str], default: None ) –

  Optional message ID. Defaults to the last received message.

speech_playback_complete async

speech_playback_complete(session_id: Optional[str] = None, message_id: Optional[str] = None)

Notify the server that speech playback has completed for a message.

Parameters:

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.

• message_id (Optional[str], default: None ) –

  Optional message ID. Defaults to the last received message.

Discovery

Fetch available assets from the Voxta server.

High-level client for interacting with the Voxta conversational AI platform.

Functions

load_characters_list async

load_characters_list()

Request the list of available characters.

load_scenarios_list async

load_scenarios_list()

Request the list of available scenarios.

load_chats_list async

load_chats_list(character_id: Optional[str] = None, scenario_id: Optional[str] = None)

Request the list of available chats.

Parameters:

• character_id (Optional[str], default: None ) –

  Optional filter by character ID.

• scenario_id (Optional[str], default: None ) –

  Optional filter by scenario ID.

Debugging

Tools for inspecting the internal state and SignalR traffic.

High-level client for interacting with the Voxta conversational AI platform.

Attributes

session_id instance-attribute

session_id: Optional[str] = None

is_speaking instance-attribute

is_speaking = False

is_thinking instance-attribute

is_thinking = False

last_message_id instance-attribute

last_message_id: Optional[str] = None

Functions

inspect async

inspect(session_id: str, enabled: bool = True)

Toggle session debug state.

Parameters:

• session_id (str) –

  The session ID.

• enabled (bool, default: True ) –

  Whether to enable or disable inspection.

inspect_audio_input async

inspect_audio_input(enabled: bool, session_id: Optional[str] = None)

Toggle audio input inspection mode.

Parameters:

• enabled (bool) –

  Whether to enable or disable inspection.

• session_id (Optional[str], default: None ) –

  Optional session ID. Defaults to the active session.