Spectrum-TS

Choose a setup method

Start with one method for a call path. Combining SDK tracking with framework OpenTelemetry on the same call can create duplicate interactions.

Recommended: Voxmith skill

Install the skill once in your coding-agent environment:

npx skills add Voxmith/skills --skill voxmith

Run the framework-specific prompt below from the application root. Review the resulting diff before deploying it.

Use the voxmith skill to add Voxmith analytics to this Spectrum-TS application.
Org ID: your-org-id
Instrument the real message-handling path and verify one fresh interaction.

Manual setup: Voxmith SDK

npm install voxmithai

Wrap the handler that turns an incoming provider message into the reply sent by your Spectrum application:

import * as voxmith from 'voxmithai';

voxmith.init('your-org-id');
const interaction = voxmith.begin({
  userId: message.userId,
  conversationId: message.conversationId,
  agentName: 'spectrum-assistant',
  input: message.text,
});
try {
  const reply = await createReply(message);
  interaction.end(reply.text);
  return reply;
} catch (error) {
  interaction.end(String(error), false);
  throw error;
}

Call await voxmith.shutdown() during application shutdown so buffered events flush.

Manual setup: OpenTelemetry

Spectrum-TS has built-in OpenTelemetry instrumentation. Enable it with telemetry: true, then route its OTLP exporter to Voxmith with standard OTEL_EXPORTER_OTLP_* environment variables.

Note: Spectrum telemetry is exported by the spectrum-ts package itself, so the app must have spectrum-ts installed. The umbrella package includes the official provider packages; install a scoped @spectrum-ts/* package only if the app imports that provider directly.

1. Install

Already have spectrum-ts installed? Skip.

npm install spectrum-ts

Official provider imports:

2. Point Spectrum telemetry at Voxmith

Set these environment variables before starting the Spectrum app. Use your runtime's environment configuration, a .env file, container configuration, or your deployment platform:

VOXMITH_ORG_ID=<your-org-id>
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.voxmith.com/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="X-Voxmith-Org-ID=<your-org-id>"

3. Enable Spectrum telemetry

import { Spectrum } from "spectrum-ts";
import { telegram } from "spectrum-ts/providers/telegram";

const app = await Spectrum({
  projectId: process.env.PROJECT_ID!,
  projectSecret: process.env.PROJECT_SECRET!,
  providers: [
    // Telegram is only an example. Any official Spectrum provider works with
    // the same telemetry config.
    telegram.config({ botToken: process.env.TELEGRAM_BOT_TOKEN! }),
  ],
  telemetry: true,
});

// Optional smoke-test loop only. Spectrum telemetry is enabled above; keep this
// only if you want the sample app to reply to messages.
for await (const [space, message] of app.messages) {
  if (message.content.type !== "text") continue;

  const output = `Echo: ${message.content.text}`;
  await space.send(output);
}

telemetry: true sends Spectrum's native spans for provider, space, message, content type, and lifecycle metadata. Current Spectrum native spans do not include raw transcript text. If Voxmith Chat View must render the actual user/bot messages, emit one additional app-level turn span with voxmith.session_id, voxmith.user_id, input, and output from your message loop.

Local Sample

npm create spectrum-project@latest clank -- --providers telegram
cd clank

Set the sample's environment variables using the mechanism appropriate for your local runtime:

PROJECT_ID=<spectrum-project-id>
PROJECT_SECRET=<spectrum-project-secret>
TELEGRAM_BOT_TOKEN=<telegram-bot-token>
VOXMITH_ORG_ID=<your-org-id>
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.voxmith.com/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="X-Voxmith-Org-ID=<your-org-id>"

Use the provider you need, for example telegram, slack, whatsapp-business, imessage, or terminal. Then set telemetry: true in the generated Spectrum(...) config. Native Spectrum telemetry is enough for Trace View and Metadata. Add a separate turn span only if you need transcript text in Chat View.

References

• Spectrum-TS telemetry
• Spectrum-TS repository

Next steps

• Conversations: review the complete Spectrum interaction.
• Events: inspect provider and message lifecycle activity.
• Intents: organize production conversations by what users wanted.