API Reference

Complete reference for every class, method, type, and event in the SDK.

XpectrumChat

typescript

import { XpectrumChat } from '@xpectrum/sdk';

Constructor

typescript

const chat = new XpectrumChat(config: XpectrumChatConfig);

Property	Type	Required	Default	Description
baseUrl	string	Yes	—	Chat API base URL (e.g. https://app.yourserver.com/api/v1)
apiKey	string	Yes	—	API key — sent as Authorization: Bearer {apiKey}
user	string	No	'sdk-user'	User identifier for conversation history
inputs	Record<string, any>	No	{}	Default input variables for every message

Methods

Method	Returns	Description
sendMessage(query, options?)	Promise<string \| undefined>	Send a message and stream response. Returns taskId.
stopResponse(taskId)	Promise<void>	Stop a response mid-generation.
getConversations(opts?)	Promise<{ data, has_more }>	List conversations. opts: { limit?, lastId?, pinned? }
getMessages(convId, opts?)	Promise<{ data, has_more }>	Get messages in a conversation. opts: { limit?, lastId? }
deleteConversation(id)	Promise<void>	Delete a conversation.
renameConversation(id, name)	Promise<void>	Rename a conversation.
generateConversationName(id)	Promise<Conversation>	Auto-generate a name based on content.
pinConversation(id)	Promise<void>	Pin a conversation.
unpinConversation(id)	Promise<void>	Unpin a conversation.
getAppInfo()	Promise<AppInfo>	Get app title, icon, description.
getAppParams()	Promise<AppParams>	Get opening statement, features, config.
submitFeedback(msgId, rating)	Promise<void>	Like/dislike/clear feedback. rating: 'like' \| 'dislike' \| null
getSuggestedQuestions(msgId)	Promise<string[]>	Get AI-suggested follow-up questions.
speechToText(audioFile)	Promise<string>	Convert audio File to text.
destroy()	void	Abort all streams, clean up.

SendMessageOptions

Property	Type	Required	Default	Description
conversationId	string	No	—	Resume an existing conversation.
inputs	Record<string, any>	No	—	Override default inputs for this message.
files	MessageFile[]	No	—	Attached files (images).
onMessage	(text, messageId, conversationId) => void	No	—	Text chunks — text accumulates the full answer.
onThought	(thought: ThoughtEvent) => void	No	—	Agent reasoning steps.
onFile	(file: FileEvent) => void	No	—	File attachments from the agent.
onMessageEnd	(metadata: MessageEndEvent) => void	No	—	Response complete with metadata.
onMessageReplace	(text, messageId) => void	No	—	Content moderation replaced the answer.
onTTSChunk	(messageId, audioBase64) => void	No	—	TTS audio chunk (base64).
onTTSEnd	(messageId, audioBase64) => void	No	—	TTS complete.
onError	(error: ErrorEvent) => void	No	—	Error during streaming.
onCompleted	() => void	No	—	Stream closed.
getAbortController	(controller) => void	No	—	Access the AbortController.

MessageFile

Property	Type	Required	Default	Description
type	'image'	Yes	—	File type.
transfer_method	'remote_url' \| 'local_file'	Yes	—	How the file is provided.
url	string	No	—	URL for remote_url method.
upload_file_id	string	No	—	File ID for local_file method.

ThoughtEvent

Property	Type	Required	Default	Description
id	string	Yes	—	Thought ID.
thought	string	Yes	—	What the agent is thinking.
observation	string	No	—	Result from a tool.
tool	string	No	—	Tool name being used.
tool_input	string	No	—	Input passed to the tool.
message_id	string	Yes	—	Parent message ID.
position	number	Yes	—	Order in the sequence.

MessageEndEvent

Property	Type	Required	Default	Description
task_id	string	Yes	—	Task identifier.
message_id	string	Yes	—	Message identifier.
conversation_id	string	Yes	—	Conversation identifier.
metadata.usage	{ prompt_tokens, completion_tokens, total_tokens, total_price, currency }	No	—	Token usage stats.
metadata.retriever_resources	Array<{ dataset_name, document_name, content, score, ... }>	No	—	RAG source documents.

Conversation

Property	Type	Required	Default	Description
id	string	Yes	—	Conversation ID.
name	string	Yes	—	Conversation name/title.
inputs	Record<string, any>	Yes	—	Input variables used.
status	string	Yes	—	Conversation status.
introduction	string	Yes	—	Opening statement.
created_at	number	Yes	—	Unix timestamp.
updated_at	number	Yes	—	Unix timestamp.

Message

Property	Type	Required	Default	Description
id	string	Yes	—	Message ID.
conversation_id	string	Yes	—	Parent conversation.
query	string	Yes	—	User's question.
answer	string	Yes	—	AI's response.
message_files	Array<{ id, type, url, belongs_to }>	Yes	—	Attached files.
feedback	{ rating: 'like' \| 'dislike' \| null } \| null	Yes	—	User feedback.
retriever_resources	Array<{ dataset_name, document_name, content, score }>	Yes	—	RAG sources.
agent_thoughts	ThoughtEvent[]	Yes	—	Reasoning steps.
created_at	number	Yes	—	Unix timestamp.

AppInfo

Property	Type	Required	Default	Description
app_id	string	Yes	—	App identifier.
title	string	Yes	—	App display title.
description	string	Yes	—	App description.
icon_type	string	Yes	—	Icon type (emoji, url, etc.).
icon	string	Yes	—	Icon value.
icon_background	string	Yes	—	Icon background color.
icon_url	string \| null	Yes	—	Icon image URL if applicable.

XpectrumVoice

typescript

import { XpectrumVoice } from '@xpectrum/sdk';

Constructor

typescript

const voice = new XpectrumVoice(config: XpectrumVoiceConfig);

Property	Type	Required	Default	Description
baseUrl	string	Yes	—	FastAPI voice server URL.
apiKey	string	Yes	—	API key — sent as x-api-key header.
agentName	string	Yes	—	Agent UUID or name to connect to.

Methods

Method	Returns	Description
connect(callbacks?)	Promise<void>	Start a voice call. Callbacks are optional (can use events instead).
disconnect()	Promise<void>	End the call, clean up audio, notify server.
setMicEnabled(enabled)	Promise<void>	Mute (false) or unmute (true) the microphone.
isMicEnabled()	boolean	Check if mic is currently enabled.
getConnectionState()	VoiceConnectionState	Get current state: 'disconnected' \| 'connecting' \| 'connected' \| 'reconnecting' \| 'failed'
getRoomName()	string \| null	Get LiveKit room name (null if not connected).
isConnected()	boolean	Shorthand for getConnectionState() === 'connected'.
on(event, handler)	() => void	Subscribe to event. Returns unsubscribe function.
off(event, handler)	void	Unsubscribe from event.
removeAllListeners(event?)	void	Remove all listeners (optionally for specific event).
destroy()	void	Disconnect + remove all listeners.

VoiceConnectCallbacks

Property	Type	Required	Default	Description
onConnected	(roomName: string) => void	No	—	Call connected.
onDisconnected	(reason: string) => void	No	—	Call ended.
onTranscription	(segment: TranscriptionSegment) => void	No	—	Speech transcribed.
onAgentSpeaking	(isSpeaking: boolean) => void	No	—	Agent started/stopped speaking.
onConnectionStateChanged	(state: VoiceConnectionState) => void	No	—	State transition.
onReconnecting	() => void	No	—	Network reconnecting.
onReconnected	() => void	No	—	Network reconnected.
onError	(error: { message, code? }) => void	No	—	Error occurred.

TranscriptionSegment

Property	Type	Required	Default	Description
id	string	Yes	—	Segment ID. Interim results share the same ID.
text	string	Yes	—	Transcribed text.
isFinal	boolean	Yes	—	true when finalized.
speaker	'user' \| 'agent'	Yes	—	Who spoke.

Voice Events

Event	Payload
'connected'	{ roomName: string }
'disconnected'	{ reason: string }
'transcription'	TranscriptionSegment
'agentSpeaking'	{ isSpeaking: boolean }
'connectionStateChanged'	{ state: VoiceConnectionState }
'reconnecting'	{}
'reconnected'	{}
'error'	{ message: string; code?: string }
'microphoneChanged'	{ enabled: boolean }

XpectrumApiError

typescript

import { XpectrumApiError } from '@xpectrum/sdk';

Property	Type	Required	Default	Description
name	'XpectrumApiError'	Yes	—	Error name (always 'XpectrumApiError').
message	string	Yes	—	Human-readable error message.
code	string	Yes	—	Error code string.
status	number	Yes	—	HTTP status code (401, 403, 404, 429, 500, etc.).

Widgets

ChatWidget

typescript

import { ChatWidget } from '@xpectrum/sdk';

Methods: open(), close(), toggle(), destroy()

VoiceWidget

typescript

import { VoiceWidget } from '@xpectrum/sdk';

Methods: open(), close(), toggle(), destroy()

OmnichannelWidget

typescript

import { OmnichannelWidget } from '@xpectrum/sdk';

Methods: openChat(), openVoice(), close(), destroy()

See the Widgets Guide for full config options and examples.

TypeScript Type Imports

typescript

import type {
  // Chat
  XpectrumChatConfig,
  SendMessageOptions,
  MessageFile,
  ThoughtEvent,
  FileEvent,
  MessageEndEvent,
  ErrorEvent,
  Conversation,
  ConversationListResponse,
  Message,
  MessageListResponse,
  AppInfo,
  AppParams,

  // Voice
  XpectrumVoiceConfig,
  TokenResponse,
  VoiceConnectionState,
  VoiceEventMap,
  VoiceConnectCallbacks,
  TranscriptionSegment,

  // Core
  RequestOptions,
  ApiError,
  SSEEvent,
  SSEMessageData,
  EventHandler,
  UnsubscribeFn,

  // Widgets
  ChatWidgetConfig,
  VoiceWidgetConfig,
  OmnichannelWidgetConfig,
} from '@xpectrum/sdk';

Internal API Endpoints

These are the HTTP endpoints the SDK calls internally. You don't call them directly — this is for reference/debugging.

Chat

Method	Endpoint	SDK Method
POST	/chat-messages	sendMessage()
POST	/chat-messages/{taskId}/stop	stopResponse()
GET	/conversations	getConversations()
GET	/messages?conversation_id={id}	getMessages()
DELETE	/conversations/{id}	deleteConversation()
POST	/conversations/{id}/name	renameConversation() / generateConversationName()
PATCH	/conversations/{id}/pin	pinConversation()
PATCH	/conversations/{id}/unpin	unpinConversation()
GET	/site	getAppInfo()
GET	/parameters	getAppParams()
POST	/messages/{id}/feedbacks	submitFeedback()
GET	/messages/{id}/suggested-questions	getSuggestedQuestions()
POST	/audio-to-text	speechToText()

Voice

Method	Endpoint	SDK Method
POST	/tokens/generate?agent_name={name}	connect()
POST	/call-control/end-call	disconnect()