Hub Endpoints

A hub endpoint is the network address a client uses after Thalovant creates its identity.

Public hubs expose only the protocols enabled for that hub. WSS is the default public path. HTTPS and MQTT are optional.

At A Glance

Endpoint type	Best for
WSS	Realtime clients, event listeners, voice flows, and agents.
HTTPS	One request, one response, health checks, CLIs, server jobs, and tests.
MQTT over TLS	Broker-mediated device, edge, or network-constrained traffic.
Same identity	All transports use the same client identity and access policy.

Identity Endpoint Fields

The SDKs prefer explicit data-plane endpoints when the identity includes them.

{
  "data_plane_endpoints": {
    "wss": "wss://jokes.thalovant.io/public",
    "https": "https://jokes.thalovant.io/public",
    "mqtt": "mqtts://mqtt.thalovant.com:8883"
  },
  "protocols": {
    "wss": { "enabled": true },
    "http": { "enabled": true },
    "mqtt": { "enabled": true }
  }
}

Older or minimal identities may use these fields:

Field	Meaning
`default_master`	Hub host or full HTTPS address.
`default_port`	Port to use when the host does not already include one.
`default_path`	Optional path prefix used by routed public hubs.

When To Use WSS

Choose WSS first when the client can keep a connection open.

Live agent

An agent keeps a session active and reacts to replies, policy events, or display updates.

Voice flow

A voice client sends utterances and listens for speech responses.

Event subscriber

A client listens for hub events and maps them into an app-specific state model.

When To Use HTTPS

Choose HTTPS when the client needs a direct answer and does not need a live socket.

Server task

A job sends one user request, reads the reply, and exits.

CLI

A developer or support tool sends diagnostics and prints the result.

Test client

A test checks auth, endpoint routing, and response parsing.

When To Use MQTT

Choose MQTT when a broker makes the deployment simpler than direct hub traffic.

MQTT uses TLS and per-client credentials. A client identity must include the mqtt block before SDKs can use that transport.

{
  "mqtt": {
    "endpoint": "mqtts://mqtt.thalovant.com:8883",
    "username": "client-access-key",
    "password": "client-broker-password",
    "topic_prefix": "hubs/hub-id/clients/client-id",
    "tls": true
  }
}

Troubleshooting

Symptom	Check first
WSS works but HTTPS fails	Confirm HTTPS is enabled for the hub.
HTTPS works but WSS fails	Confirm the public hub exposes the WebSocket route and TLS certificate.
MQTT fails immediately	Create a fresh client identity after MQTT is enabled on the hub.
Auth fails on every transport	Recreate or rotate the client identity in Thalovant.
Requests reach the wrong route	Check `data_plane_endpoints` first, then `default_path`.