.NET SDK

Use the .NET SDK when your client runs on .NET or inside Unity.

The NuGet package name is Thalovant.Sdk. It multi-targets net8.0 and netstandard2.1, which covers Unity 2021 and newer. The net8.0 build has zero external dependencies; the netstandard2.1 target only depends on the System.Text.Json package.

Source and releases: thalovant-dotnet-sdk on GitHub.

Uses the pre-shared handshake

This SDK authenticates with the crypto_key the pre-shared handshake needs, and hubs no longer issue one, so an identity created from now on has nothing for it to use. It keeps working with an identity minted earlier that still carries the field. The v3 Noise handshake is what replaced it.

Install

dotnet add package Thalovant.Sdk

First Request

This flow signs in, creates a client identity, and sends one request over WSS.

using Thalovant;

var api = new ThalovantControlPlane();

await api.LoginAsync("[email protected]", "password");

var result = await api.CreateClientIdentityAsync(
    "hub-id",
    new CreateClientIdentityOptions("dotnet-demo-client"));

using var client = new ThalovantClient(result.Identity);
await client.ConnectAsync();
var reply = await client.AskAsync("Tell me a short clean joke.");
Console.WriteLine(reply.Text);
await client.CloseAsync();

new ThalovantControlPlane() uses https://api.thalovant.com by default.

Caution

Keep result.Identity secret. Authenticated API actions require API access on the workspace. Do not log result.ToJsonObject(includeSecrets: true).

Sign In With MFA

Accounts with multi-factor authentication enabled must include a TOTP code or a one-time recovery code with the login. Without one, the API rejects the sign-in with HTTP 401 and code mfa_required, surfaced as ThalovantApiException.ErrorCode.

await api.LoginAsync("[email protected]", "password", otpCode: "123456");

// Or use a one-time recovery code instead:
await api.LoginAsync("[email protected]", "password", recoveryCode: "abcd-efgh-ijkl");

The otpCode and recoveryCode values are sent only when provided.

Sign In Without A Password

Device login asks your browser to approve the sign-in, so services and apps never handle your password. The SDK prints a short code and the address https://dash.thalovant.com/activate, opens that page when it can, and waits while you approve the request in the dashboard with your normal sign-in, including Google sign-in or MFA. On approval the SDK holds a scoped, revocable API token, returned as a typed DeviceLoginResult.

Device login needs SDK 0.1.1 or newer. Approving the request needs a paid workspace plan; a free plan gets HTTP 402.

var result = await api.LoginWithBrowserAsync(new DeviceLoginOptions
{
    Scopes = new[] { "hubs:read", "clients:write" },
    ClientName = "my-tool",
});
Console.WriteLine($"{result.TokenId} expires {result.ExpiresAt}");

Manage the resulting token on the dashboard’s API Tokens page.

Authenticate With An API Token

Pass a stored API token when the process should start authenticated, such as CI jobs and services. Mint one on the API Tokens page or with LoginWithBrowserAsync; the page shows scopes, expiry, and last use, and can revoke the token at any time.

var api = new ThalovantControlPlane(accessToken: Environment.GetEnvironmentVariable("THALOVANT_API_TOKEN"));

WSS Only In v0.1

ThalovantClient connects to the hub over WSS only in this release. Constructing it with HubProtocol.Https or HubProtocol.Mqtt throws ThalovantUnsupportedProtocolException. Endpoint selection still prefers wss, then https, then mqtt, so identities created for multi-protocol hubs keep working.

Use the Python, Node.js, Go, or Rust SDK when the client needs the HTTPS or MQTT data plane today.

Use A Saved Identity

Identities can be built from JSON or loaded from a JSON file. On Linux and macOS the file must not be group- or world-readable; run chmod 600 <path> first. The permission check is skipped on Windows and on the netstandard2.1 Unity build.

var identity = ThalovantIdentity.FromFile("/path/to/identity.json");
using var client = new ThalovantClient(identity);

The identity document uses the same snake_case fields the API returns, including access_key, password, site_id, and the optional data_plane_endpoints, protocols, and mqtt sections. A crypto_key in an older identity file is still parsed and ignored.

Follow An Operation

Mutating control-plane commands return durable operations. Poll them with the typed helper:

var operation = await api.GetOperationAsync("operation-id");
Console.WriteLine(operation.Status);  // Requested, Committed, Applied, Ready, Failed, TimedOut

See Operations for lifecycle and retry guidance.

Listen For Events

var subscription = client.On("speak", e => Console.WriteLine(e.DisplayText));
// Later, when the listener is no longer needed:
subscription.Close();

List What The Hub Can Be Asked

A connected client can list every intent its hub answers, per language, with the sentences a person says to reach each one, over its own session and with no control-plane token. See What Can My Hub Be Asked? for what the hub returns, which message types the connection must be allowed to publish, and what a refusal or a failed listing looks like.

Since SDK 0.1.12 the calls are client.IntentsAsync(languages, options), which returns the inventory grouped by skill, client.ListIntentsAsync(lang, options), which returns the registration rows, and client.DescribeIntentAsync(skillId, intentName, lang, options), which returns the definitions behind one intent. Each takes a CancellationToken last.

try
{
    var inventory = await client.IntentsAsync(new[] { "en-us", "fr-fr" });
    Console.WriteLine($"{inventory.Source} {string.Join(", ", inventory.Languages)}");
    foreach (var skill in inventory.Skills)
    {
        foreach (var intent in skill.Intents)
        {
            Console.WriteLine($"  {intent.Id} [{intent.Engine}]: {string.Join(" | ", intent.Examples("fr-fr"))}");
        }
    }
}
catch (ThalovantPolicyDeniedException denied)
{
    Console.Error.WriteLine($"refused {denied.DeniedType}; allowed {string.Join(", ", denied.Allowed)}");
    throw;
}

IntentsAsync asks ovos.intent.list once per language, then fills in the sentences the listing did not carry, in batches of at most 32 requests so a hub with many intents is never sent the whole burst at once. IntentInventoryOptions carries the timeout and the switches: Describe = false stops at names, engines, and enabled state. Examples(lang, limit: 2) prefers whole sentences to ones with a {slot}, then shorter ones; PhrasesFor("fr-FR") finds fr-fr too, and inventory.ToJsonObject() writes the same document the other SDKs write. Language tags compare without regard to case or _ and -, so fr-fr and fr_FR are one request.

A hub that refuses a query throws ThalovantPolicyDeniedException at once with DeniedType, Code, Reason, and Allowed. With IntentInventoryOptions.Fallback on, which is the default, a refused ovos.intent.list returns names only instead: inventory.Source is engine-manifests, inventory.Denied names the refused query, and inventory.HasPhrases is false. A hub that accepts the listing and answers it with ok: false is a different case: since 0.1.13 that throws ThalovantRuntimeException carrying the hub’s own error text, because a failed listing is not an empty hub. DescribeIntentAsync keeps returning an empty list for the same answer, which is a real one: the hub does not know that registration.

Useful Helpers

AskAsync

Send one request and receive a normalized reply.

On

Observe hub bus events by name with a closeable subscription.

GetOperationAsync

Poll a durable control-plane command with a typed status.

ListPublicHubsAsync

Discover public hubs before sign-in.

For cross-language recipes, see SDK Functions.

Provision Hubs

Since SDK 0.1.5 the control plane can create hubs, runtime groups, and skill installs. Browsing the catalog with ListMarketplaceSkillsAsync() needs hubs:read and works on any plan. CreateHubAsync, CreateRuntimeGroupAsync, InstallRuntimeGroupSkillAsync, ReleaseHubAsync, and ReleaseRuntimeGroupAsync need hubs:write and a paid plan.

var group = await api.CreateRuntimeGroupAsync(new CreateRuntimeGroupOptions("kiosks"));
var hub = await api.CreateHubAsync(new CreateHubOptions("joke-garden", new JsonObject())
{
    RuntimeGroupId = (string)group["id"]!,
});

hub = await api.GetHubAsync((string)hub["id"]!);
await api.UpdateHubAsync((string)hub["id"]!, new UpdateHubOptions { Active = false }, (string)hub["etag"]!);

UpdateHubAsync and DeleteHubAsync take the hub’s current etag as a required argument. See Provision Hubs for the full flow, the immutable fields, and the error table.

Common Issues

Symptom	Check
ThalovantApiException with Missing Thalovant API access token	Call api.LoginAsync(...) or api.LoginWithBrowserAsync(...) before private API actions, or pass accessToken: to ThalovantControlPlane.
HTTP 401 with ErrorCode mfa_required	Pass otpCode or recoveryCode to api.LoginAsync(...).
API access requires a paid plan	Upgrade the workspace before provisioning private resources through the API.
ThalovantUnsupportedProtocolException	The hub does not expose WSS, or the code requested Https or Mqtt, which this release does not connect over.
ThalovantIdentityException	The identity file is malformed or readable by other users.