Client API

A client is a separate process that talks to the Voxta server over its SignalR / WebSocket hub. Voxta Talk, the VAM plugin, the Minecraft companion and Voxy are all clients of the same API.

Write a client when your code has to run where Voxta can't — a game's scripting engine, a Node bot, a browser, an embedded device. Write a module instead when it can live as .NET inside the server.

Connecting

The hub is at /hub on the server (http://127.0.0.1:5384 by default), over the WebSockets transport:

const connection = new signalR.HubConnectionBuilder()
  .withUrl('http://127.0.0.1:5384/hub', {
    skipNegotiation: true,
    transport: signalR.HttpTransportType.WebSockets,
  })
  .withAutomaticReconnect()
  .build();

Everything then flows through two hub methods:

Every message is discriminated by a $type field.

Authenticating

authenticate must be the first message, and again after a reconnect:

connection.send('SendMessage', {
  $type: 'authenticate',
  client: 'MyGame',
  clientVersion: '1.0.0',
  scope: ['role:app'],
  capabilities: {},
});

capabilities tells the server what your client can do with audio, so it knows whether to generate speech for you and in what form. Declaring nothing gets URL-based audio output and no microphone.

Starting a chat

Once authenticated, startChat (or resumeChat for an existing one) opens a session. From there the server streams what the character is doing — replyChunk as the text and audio are produced, speechPlaybackStart / speechPlaybackComplete to be told and to report back, action and appTrigger for what the scenario wants your app to do.

What a client can offer

Worked examples