API Documentation

Vue SDK

Add real-time voice interactions to your Vue 3 app with composables or a headless component.

Installation

npm install @itannix/vue

Quick Start (Composable)

Use the useVoiceClient composable for full control over the voice client:

App.vue

<script setup lang="ts">
import { ref } from 'vue';
import { useVoiceClient } from '@itannix/vue';

const messages = ref<{ role: string; text: string }[]>([]);

const { status, connect, disconnect, sendFunctionResult } = useVoiceClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  onTranscript: (transcript) => {
    messages.value.push({ role: 'user', text: transcript });
  },
  onAssistantMessage: (text, done) => {
    if (done) {
      messages.value.push({ role: 'assistant', text });
    }
  },
  onError: (error) => console.error('Voice error:', error)
});
</script>

<template>
  <div>
    <p>Status: {{ status }}</p>
    <button @click="connect" :disabled="status !== 'disconnected'">
      Connect
    </button>
    <button @click="disconnect" :disabled="status === 'disconnected'">
      Disconnect
    </button>
    <p v-for="(msg, i) in messages" :key="i">
      <strong>{{ msg.role }}:</strong> {{ msg.text }}
    </p>
  </div>
</template>

Quick Start (Component)

Alternatively, use the headless VoiceAssistant component with template refs:

App.vue

<script setup lang="ts">
import { ref } from 'vue';
import { VoiceAssistant } from '@itannix/vue';
import type { ConnectionStatus } from '@itannix/vue';

const assistant = ref<InstanceType<typeof VoiceAssistant> | null>(null);
const status = ref<ConnectionStatus>('disconnected');
const messages = ref<{ role: string; text: string }[]>([]);

function handleConnect() {
  assistant.value?.connect();
}

function handleDisconnect() {
  assistant.value?.disconnect();
}
</script>

<template>
  <div>
    <VoiceAssistant
      ref="assistant"
      client-id="your-client-id"
      client-secret="your-client-secret"
      @status-change="(s) => status = s"
      @transcript="(t) => messages.push({ role: 'user', text: t })"
      @assistant-message="(text, done) => {
        if (done) messages.push({ role: 'assistant', text });
      }"
    />

    <p>Status: {{ status }}</p>
    <button @click="handleConnect" :disabled="status !== 'disconnected'">
      Connect
    </button>
    <button @click="handleDisconnect" :disabled="status === 'disconnected'">
      Disconnect
    </button>
    <p v-for="(msg, i) in messages" :key="i">
      <strong>{{ msg.role }}:</strong> {{ msg.text }}
    </p>
  </div>
</template>

Composable Options

Option	Type	Required	Description
`clientId`	MaybeRefOrGetter<string>	Yes	Your ItanniX client ID (supports reactive refs)
`clientSecret`	MaybeRefOrGetter<string>	Yes	Your client secret (32+ character random string)
`serverUrl`	MaybeRefOrGetter<string>	No	API server URL (default: 'https://api.itannix.com')
`onTranscript`	(transcript: string) => void	No	Called when user speech is transcribed
`onAssistantMessage`	(text: string, done: boolean) => void	No	Called for assistant responses. `done=true` indicates final message.
`onFunctionCall`	(name, args, callId) => void	No	Called when assistant invokes a function
`onError`	(error: Error) => void	No	Called on connection or runtime errors

Composable Return Values

`status: Ref<ConnectionStatus>`

Reactive connection status: 'disconnected', 'connecting', or 'connected'.

`connect(): Promise<void>`

Establishes WebRTC connection. Requests microphone permission and starts streaming audio.

`disconnect(): void`

Closes the connection and stops all audio streams. Safe to call even if not connected.

`sendFunctionResult(callId: string, result: object): void`

Sends a function call result back to the assistant. Use the callId from onFunctionCall.

Component Events

Event	Payload	Description
`@status-change`	ConnectionStatus	Emitted when connection status changes
`@transcript`	string	User's speech transcription (completed)
`@assistant-message`	(text: string, done: boolean)	Assistant response. `done=true` indicates final message.
`@function-call`	(name, args, callId)	Function call from assistant. Respond with exposed `sendFunctionResult()`.
`@error`	Error	Connection or runtime errors

Handling Function Calls

When the assistant invokes a function, handle it and return the result:

Function Call Handler

<script setup lang="ts">
import { useVoiceClient } from '@itannix/vue';

const { sendFunctionResult } = useVoiceClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  onFunctionCall: async (name, args, callId) => {
    if (name === 'get_weather') {
      const weather = await fetchWeather(args.location as string);
      sendFunctionResult(callId, { 
        temperature: weather.temp,
        conditions: weather.conditions
      });
    }
  }
});
</script>

TypeScript Support

The SDK is written in TypeScript and exports all types:

import { 
  VoiceAssistant,
  VoiceClient,
  useVoiceClient,
  type ConnectionStatus,
  type FunctionCallEvent,
  type AssistantMessageEvent,
  type UseVoiceClientOptions,
  type UseVoiceClientReturn
} from '@itannix/vue';