Rust SDK

Use the Rust SDK when your client needs strong types, low overhead, or careful runtime control.

The crate name is thalovant.

Install

Install the latest release with cargo add thalovant. Use the current verified version explicitly when you need reproducible builds:

cargo add [email protected]

Rust SDK v0.2.17 removes the vulnerable rustls-webpki 0.102 dependency path from MQTT. MQTT TLS uses the operating system’s native trust store; HTTPS and WSS continue to use the SDK’s Rustls transport.

First Request

use thalovant::{
    BootstrapIdentityOptions, Client, ControlPlane, HubProtocol, RequestOptions,
};

#[tokio::main]
async fn main() -> thalovant::Result<()> {
    let mut control = ControlPlane::default();

    control.login("[email protected]", "password", None).await?;

    let result = control
        .create_client_identity_for_hub_id(
            "hub-id",
            BootstrapIdentityOptions {
                name: "rust-demo-client".into(),
                preferred_protocols: vec![HubProtocol::Wss, HubProtocol::Https, HubProtocol::Mqtt],
                ..Default::default()
            },
        )
        .await?;

    let client = Client::with_protocol(result.identity.clone(), HubProtocol::Wss)?;
    let reply = client
        .ask("Tell me a short clean joke.", RequestOptions::default())
        .await?;

    println!("{}", reply.text);
    client.close().await?;

    Ok(())
}

ControlPlane::default() uses https://api.thalovant.com.

Caution

Keep result.identity secret. Authenticated API actions require API access on the workspace.

Use A Saved Identity

use thalovant::{Client, RequestOptions};

let client = Client::from_config(Some("prod"))?;
let reply = client
    .ask("What can this hub do?", RequestOptions::default())
    .await?;
println!("{}", reply.text);
client.close().await?;

Raw identity files work too:

use thalovant::{Client, RequestOptions};

let client = Client::from_file("_identity.json")?;
let reply = client
    .ask("What can this hub do?", RequestOptions::default())
    .await?;
println!("{}", reply.text);
client.close().await?;

Environment variables work too:

use thalovant::Client;

let client = Client::from_env()?;

Choose A Protocol

let identity = result.identity.clone();

println!("{:?}", identity.enabled_protocols());
println!("{:?}", identity.endpoint_for(HubProtocol::Wss));
println!("{:?}", identity.endpoint_for(HubProtocol::Https));
println!("{:?}", identity.endpoint_for(HubProtocol::Mqtt));

for protocol in [HubProtocol::Wss, HubProtocol::Https, HubProtocol::Mqtt] {
    if !identity.supports_protocol(protocol) {
        continue;
    }
    if protocol == HubProtocol::Mqtt && identity.mqtt.is_none() {
        continue;
    }

    let client = Client::with_protocol(identity.clone(), protocol)?;
    let reply = client
        .ask(&format!("Reply over {protocol:?}."), RequestOptions::default())
        .await?;
    println!("{protocol:?}: {}", reply.text);
    client.close().await?;
}

MQTT requires the identity.mqtt broker credentials returned for that client.

For broker details, see MQTT.

Add Context

use thalovant::{build_client_context, ClientContextOptions, RequestOptions};

let context = build_client_context(None, ClientContextOptions {
    user_id: Some("user-42".into()),
    user_name: Some("Ada".into()),
    auth_provider: Some("oidc".into()),
    source: Some("checkout-kiosk".into()),
    platform: Some("kiosk".into()),
    locale: Some("en-US".into()),
    channel: Some("chat".into()),
    ..Default::default()
});

let reply = client
    .ask(
        "Show the next instruction.",
        RequestOptions {
            context: Some(context),
            ..Default::default()
        },
    )
    .await?;

Listen For Events

use std::time::Duration;
use thalovant::RequestOptions;
use tokio::time::timeout;

let mut events = client.transport.subscribe();
client
    .send_utterance("Say the current status.", RequestOptions::default())
    .await?;

if let Ok(Ok(event)) = timeout(Duration::from_secs(12), events.recv()).await {
    println!("{} {}", event.name, event.text());
}

Useful Helpers

ask

Send one request and receive normalized text, speech, and display items.

conversation

Keep related turns in one session.

send_action

Send a structured action from a device, UI, or service command.

send_code

Send a scanned value, serial number, QR value, or typed code.

For the full method list, see SDK Functions. Use control.get_operation(operation_id) to follow an accepted command; see Operations.

Common Issues

Symptom	Check
Missing access token	Call control.login(...) before private API actions.
API access requires a paid plan	Upgrade the workspace before provisioning private resources through the API.
Unsupported protocol	Enable that protocol on the hub and create a fresh identity.
MQTT fails immediately	Confirm the identity has identity.mqtt broker credentials.