Go SDK

Use the Go SDK when your client needs a compact service, gateway, command-line tool, or agent process.

The module path is github.com/thalovant/thalovant-go-sdk.

Install

Install with go get github.com/thalovant/thalovant-go-sdk.

go get github.com/thalovant/thalovant-go-sdk

First Request

package main

import (
  "context"
  "fmt"
  "log"

  thalovant "github.com/thalovant/thalovant-go-sdk"
)

func main() {
  ctx := context.Background()
  control := thalovant.NewDefaultControlPlane("")

  _, err := control.Login(ctx, "[email protected]", "password", "")
  if err != nil {
    log.Fatal(err)
  }

  result, err := control.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
    Name: "go-demo-client",
    PreferredProtocols: []thalovant.HubProtocol{
      thalovant.ProtocolWSS,
      thalovant.ProtocolHTTPS,
      thalovant.ProtocolMQTT,
    },
  })
  if err != nil {
    log.Fatal(err)
  }

  client, err := thalovant.NewClientWithOptions(result.Identity, thalovant.ClientOptions{
    Protocol: thalovant.ProtocolWSS,
  })
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close(ctx)

  reply, err := client.Ask(ctx, "Tell me a short clean joke.", thalovant.RequestOptions{})
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println(reply.Text)
}

NewDefaultControlPlane uses https://api.thalovant.com. Use NewControlPlane only for local development or a self-hosted control plane.

Caution

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

Use A Saved Identity

client, err := thalovant.NewClientFromConfig("", "prod")
if err != nil {
  log.Fatal(err)
}
defer client.Close(ctx)

Raw identity files work too:

client, err := thalovant.NewClientFromFile("_identity.json")
if err != nil {
  log.Fatal(err)
}
defer client.Close(ctx)

reply, err := client.Ask(ctx, "What can this hub do?", thalovant.RequestOptions{})
if err != nil {
  log.Fatal(err)
}
fmt.Println(reply.Text)

Environment variables work too:

client, err := thalovant.NewClientFromEnv()
if err != nil {
  log.Fatal(err)
}

Choose A Protocol

identity := result.Identity

fmt.Println(identity.EnabledProtocols())
fmt.Println(identity.EndpointFor(thalovant.ProtocolWSS))
fmt.Println(identity.EndpointFor(thalovant.ProtocolHTTPS))
fmt.Println(identity.EndpointFor(thalovant.ProtocolMQTT))

for _, protocol := range []thalovant.HubProtocol{
  thalovant.ProtocolWSS,
  thalovant.ProtocolHTTPS,
  thalovant.ProtocolMQTT,
} {
  if !identity.SupportsProtocol(protocol) {
    continue
  }
  if protocol == thalovant.ProtocolMQTT && identity.MQTT == nil {
    continue
  }

  client, err := thalovant.NewClientWithOptions(identity, thalovant.ClientOptions{Protocol: protocol})
  if err != nil {
    log.Fatal(err)
  }
  reply, err := client.Ask(ctx, fmt.Sprintf("Reply over %s.", protocol), thalovant.RequestOptions{})
  _ = client.Close(ctx)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(protocol, reply.Text)
}

MQTT requires the Identity.MQTT broker credentials returned for that client.

For broker details, see MQTT.

Add Context

requestContext := thalovant.BuildClientContext(nil, thalovant.ClientContextOptions{
  UserID:       "user-42",
  UserName:     "Ada",
  AuthProvider: "oidc",
  Source:       "checkout-kiosk",
  Platform:     "kiosk",
  Locale:       "en-US",
  Channel:      "chat",
})

reply, err := client.Ask(ctx, "Show the next instruction.", thalovant.RequestOptions{
  Context: requestContext,
})

Listen For Events

events := client.Transport.Events()

if err := client.SendUtterance(ctx, "Say the current status.", thalovant.RequestOptions{}); err != nil {
  log.Fatal(err)
}

select {
case event := <-events:
  fmt.Println(event.Name, event.Text())
case <-time.After(12 * time.Second):
  log.Fatal("timed out waiting for a hub event")
}

Useful Helpers

Ask

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

Conversation

Keep related turns in one session.

SendAction

Send a button, menu, or tool action.

SendCode

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

For the full method list, see SDK Functions.

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.