Introduction

TTP Agent SDK is a powerful JavaScript library for building AI-powered voice and chat interactions in your web applications.

Installation

NPM

npm install ttp-agent-sdk

CDN

<script src="https://unpkg.com/ttp-agent-sdk/dist/agent-widget.js"></script>

Import

// ES6 Import
import { VoiceSDK } from 'ttp-agent-sdk';

// CommonJS
const { VoiceSDK } = require('ttp-agent-sdk');

// Browser Global
const sdk = new window.TTPAgentSDK.VoiceSDK(config);

Quick Start

Get up and running in 5 minutes with this simple example.

const response = await fetch('/api/get-voice-session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agentId: 'agent_123'
  })
});

const { signedUrl } = await response.json();

import { VoiceSDK } from 'ttp-agent-sdk';

const voiceSDK = new VoiceSDK({
  signedUrl: signedUrl,  // signedUrl from step 1
  appId: 'your_app_id',     // Your application ID
  agentId: 'agent_123',     // The AI agent to connect to
  
  // Optional: Configure audio formats (v2 protocol)
  outputContainer: 'raw',      // 'raw' or 'wav'
  outputEncoding: 'pcm',       // 'pcm', 'pcmu', 'pcma'
  outputSampleRate: 44100,     // Higher quality audio
  protocolVersion: 2           // Use v2 protocol for format negotiation
});

// Listen to events
voiceSDK.on('connected', () => {
  console.log('✅ Connected to agent');
});

voiceSDK.on('formatNegotiated', (format) => {
  console.log('✅ Format negotiated:', format);
  // Format contains: container, encoding, sampleRate, channels, bitDepth
});

voiceSDK.on('message', (msg) => {
  if (msg.t === 'agent_response') {
    console.log('Agent:', msg.agent_response);
  }
});

// Connect
await voiceSDK.connect();

// Start recording
await voiceSDK.startRecording();

// Stop recording
await voiceSDK.stopRecording();

Authentication

TTP Agent SDK uses signed WebSocket URLs for secure authentication.

Authentication Flow

Backend Implementation (Backend-to-Backend)

Your backend acts as a secure proxy between your frontend and TTP backend:

// Example: Node.js/Express
// This endpoint is called by YOUR FRONTEND
app.post('/api/get-voice-session', async (req, res) => {
  const { agentId } = req.body;
  
  // 1️⃣ Authenticate YOUR user (your auth logic)
  if (!req.user) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  // 2️⃣ Backend-to-Backend: Call TTP Backend with YOUR API Key
  // ⚠️ This happens SERVER-SIDE only - API key never exposed to frontend
  const response = await fetch('https://backend.talktopc.com/api/public/agents/signed-url', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.TTP_API_KEY}`  // 🔒 Secret - never in frontend!
    },
    body: JSON.stringify({
      agentId: agentId,
      appId: process.env.TTP_APP_ID,
      expirationMs: 3600000,  // Optional: Token TTL in milliseconds (default: 1 hour)
      allowOverride: true     // Optional: Enable agent settings override (default: false)
    })
  });
  
  const { signedLink } = await response.json();
  
  // 3️⃣ Return signed URL to YOUR frontend
  res.json({ signedUrl: signedLink });
});

Response Format

The signed URL endpoint returns the following response:

{
  "signedLink": "wss://speech.talktopc.com/ws/conv?signed_token=eyJ...",
  "agentId": "agent_123",
  "userId": "user_789",
  "appId": "your_app_id",
  "expiresAt": "2025-11-11T21:00:00.000+00:00",
  "expiresIn": 3600000,
  "generatedAt": "2025-11-11T20:00:00.000+00:00",
  "availableCredits": 150.5,
  "authenticationStatus": "SUCCESS"
}

JWT Token Properties

Request Parameters

Agent Settings Override

NEW FEATURE

Dynamically customize agent behavior, voice, and personality on a per-session basis.

How It Works

1. Backend-to-Backend: Your backend requests a signed URL from TTP backend with allowOverride: true
2. Backend → Frontend: Your backend returns the signed URL to your frontend
3. Frontend: Your frontend uses the SDK with the signed URL + custom agent settings
4. TTP Backend: Validates the JWT signature and applies your overrides if permission granted

Example

const voiceSDK = new VoiceSDK({
  signedUrl: signedUrl,  // signedUrl from your backend
  appId: 'your_app_id',     // Your application ID
  agentId: 'agent_123',     // The AI agent to connect to
  
  // Override agent settings
  agentSettingsOverride: {
    // Core settings
    prompt: "You are a friendly Spanish-speaking travel assistant",
    language: "es",
    temperature: 0.9,
    maxTokens: 200,
    
    // Voice settings
    voiceSpeed: 1.2,
    voiceId: "nova",  // Use voiceId (not selectedVoice)
    
    // Behavior
    firstMessage: "¡Hola! ¿Cómo puedo ayudarte hoy?",
    disableInterruptions: false,
    autoDetectLanguage: true,
    
    // Tools (optional)
    toolIds: [123, 456, 789],              // Custom tool IDs
    internalToolIds: ['calendar', 'email'] // Internal tool IDs
  }
});

Available Override Settings

15 out of 16 settings can be overridden. Only model selection is not supported (requires infrastructure changes).

Variables in Hello Request

Overview

Variables allow you to pass dynamic values to your agent that will be used to replace placeholders in the system prompt and first message. Variables sent in the hello request take precedence over default variables stored in the agent configuration.

Hello Message Format

SDK v2 Format (Recommended)

When using VoiceSDK v2, variables are passed in the SDK constructor:

import { VoiceSDK_v2 } from 'ttp-agent-sdk';

// Get signed URL from your backend first
const response = await fetch('/api/get-voice-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ agentId: 'agent_5a2b984c1', appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC' })
});
const { signedUrl } = await response.json();

const voiceSDK = new VoiceSDK_v2({
  signedUrl: signedUrl,  // Use signedUrl from backend
  agentId: 'agent_5a2b984c1',
  appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC',
  
  // Variables (optional)
  variables: {
    USER_NAME: 'John',
    ACCOUNT_TYPE: 'premium',
    LANGUAGE: 'en-US'
  },
  
  // Audio format configuration
  sampleRate: 44100,
  channels: 1,
  bitDepth: 16,
  outputContainer: 'raw',
  outputEncoding: 'pcm',
  outputSampleRate: 44100,
  outputChannels: 1,
  outputBitDepth: 16,
  outputFrameDurationMs: 600
});

await voiceSDK.connect();

Raw WebSocket Format

If connecting via raw WebSocket (without SDK), send variables in the hello message:

{
  "t": "hello",
  "v": 2,
  "variables": {
    "USER_NAME": "John",
    "ACCOUNT_TYPE": "premium",
    "LANGUAGE": "en-US"
  },
  "inputFormat": {
    "encoding": "pcm",
    "sampleRate": 44100,
    "channels": 1,
    "bitDepth": 16
  },
  "requestedOutputFormat": {
    "encoding": "pcm",
    "sampleRate": 44100,
    "channels": 1,
    "bitDepth": 16,
    "container": "raw"
  },
  "outputFrameDurationMs": 600
}

Variable Format

Variables are sent as a JSON object where:

• Keys: Variable names (case-sensitive, e.g., USER_NAME)
• Values: String values that will replace {{VARIABLE_NAME}} in the prompt

Example

{
  "variables": {
    "USER_NAME": "John",
    "ACCOUNT_TYPE": "premium",
    "LANGUAGE": "en-US",
    "COMPANY": "Acme Corp"
  }
}

Variable Replacement Priority

Variables are replaced in the following priority order:

1. Hello Variables (highest priority) - Variables sent in the hello request
2. Default Variables - Variables stored in agent configuration (Redis)
3. Leave as-is - If no value found, {{VARIABLE_NAME}} remains unchanged

Example Priority

Agent Configuration (Redis):

{
  "USER_NAME": "David",
  "ACCOUNT_TYPE": "premium"
}

Hello Request:

{
  "variables": {
    "USER_NAME": "John"
  }
}

Result:

• {{USER_NAME}} → "John" (from hello - takes precedence)
• {{ACCOUNT_TYPE}} → "premium" (from defaults - hello doesn't override)

Usage Examples

Example 1: JavaScript/TypeScript with SDK v2

import { VoiceSDK_v2 } from 'ttp-agent-sdk';

// Get signed URL from your backend first
const response = await fetch('/api/get-voice-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ agentId: 'agent_5a2b984c1', appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC' })
});
const { signedUrl } = await response.json();

const voiceSDK = new VoiceSDK_v2({
  signedUrl: signedUrl,  // Use signedUrl from backend
  agentId: 'agent_5a2b984c1',
  appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC',
  
  variables: {
    USER_NAME: 'John Doe',
    ACCOUNT_TYPE: 'premium',
    LANGUAGE: 'en-US'
  },
  
  // ... audio format config
});

await voiceSDK.connect();

Example 2: Raw WebSocket (JavaScript)

const ws = new WebSocket('wss://speech.talktopc.com/ws/conv?agentId=agent_5a2b984c1&appId=app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC');

ws.onopen = () => {
  const helloMessage = {
    t: 'hello',
    v: 2,
    variables: {
      USER_NAME: 'John',
      ACCOUNT_TYPE: 'premium',
      LANGUAGE: 'en-US'
    },
    inputFormat: {
      encoding: 'pcm',
      sampleRate: 44100,
      channels: 1,
      bitDepth: 16
    },
    requestedOutputFormat: {
      encoding: 'pcm',
      sampleRate: 44100,
      channels: 1,
      bitDepth: 16,
      container: 'raw'
    },
    outputFrameDurationMs: 600
  };
  
  ws.send(JSON.stringify(helloMessage));
};

Example 3: Python WebSocket

import websocket
import json

def on_open(ws):
    hello_message = {
        "t": "hello",
        "v": 2,
        "variables": {
            "USER_NAME": "John",
            "ACCOUNT_TYPE": "premium",
            "LANGUAGE": "en-US"
        },
        "inputFormat": {
            "encoding": "pcm",
            "sampleRate": 44100,
            "channels": 1,
            "bitDepth": 16
        },
        "requestedOutputFormat": {
            "encoding": "pcm",
            "sampleRate": 44100,
            "channels": 1,
            "bitDepth": 16,
            "container": "raw"
        },
        "outputFrameDurationMs": 600
    }
    
    ws.send(json.dumps(hello_message))

ws = websocket.WebSocketApp(
    "wss://speech.talktopc.com/ws/conv?agentId=agent_5a2b984c1&appId=app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC",
    on_open=on_open
)
ws.run_forever()

Example 4: cURL / wscat

# Using wscat
wscat -c "wss://speech.talktopc.com/ws/conv?agentId=agent_5a2b984c1&appId=app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC"

# Then send:
{"t":"hello","v":2,"variables":{"USER_NAME":"John","ACCOUNT_TYPE":"premium"},"inputFormat":{"encoding":"pcm","sampleRate":44100,"channels":1,"bitDepth":16},"requestedOutputFormat":{"encoding":"pcm","sampleRate":44100,"channels":1,"bitDepth":16,"container":"raw"},"outputFrameDurationMs":600}

Agent Prompt Setup

To use variables in your agent, include placeholders in the system prompt or first message:

System Prompt Example

Your name is {{AGENT_NAME}}.
You are helping {{USER_NAME}} who has a {{ACCOUNT_TYPE}} account.
Speak in {{LANGUAGE}}.

First Message Example

Hello {{USER_NAME}}! Welcome to our {{ACCOUNT_TYPE}} service.

Backend Processing

When the hello request is received with variables:

1. Variables are extracted from the hello message
2. Default variables are loaded from agent configuration (Redis)
3. Variables are merged (hello variables take precedence)
4. Prompt is processed - {{VARIABLE_NAME}} placeholders are replaced
5. First message is processed - Variables are replaced here too
6. Metadata is added - Variables metadata section is appended to prompt

Server Logs

After sending hello with variables, check server logs for:

📝 Processing variables from hello message: [USER_NAME, ACCOUNT_TYPE, LANGUAGE]
✅ Variables processed and prompt updated
📝 FINAL PROCESSED PROMPT (agentId: ...):
[Prompt with variables replaced]
✅ Processed variables: 3 hello variables, 2 default variables, metadata: added

Variable Naming Conventions

• Use UPPERCASE with underscores: USER_NAME, ACCOUNT_TYPE
• Variable names are case-sensitive
• Avoid special characters except underscores
• Recommended format: {{VARIABLE_NAME}} in prompts

Common Use Cases

1. User Personalization

{
  "variables": {
    "USER_NAME": "John Doe",
    "USER_EMAIL": "john@example.com"
  }
}

2. Account Context

{
  "variables": {
    "ACCOUNT_TYPE": "premium",
    "SUBSCRIPTION_STATUS": "active"
  }
}

3. Language/Localization

{
  "variables": {
    "LANGUAGE": "en-US",
    "CURRENCY": "USD"
  }
}

4. Session Context

{
  "variables": {
    "SESSION_ID": "abc123",
    "PAGE_URL": "https://example.com/products"
  }
}

Error Handling

Missing Variables

If a variable is referenced in the prompt but not provided:

• Has default value: Uses default from agent configuration
• No default value: Placeholder remains unchanged ({{VARIABLE_NAME}})

Invalid Variable Format

• Variables must be a JSON object
• Values should be strings (will be converted to string if needed)
• Empty object {} or null is valid (will use defaults only)

Best Practices

1. Set defaults in agent configuration for all variables
2. Override with hello variables only when you have dynamic values
3. Use descriptive names that clearly indicate the variable's purpose
4. Document variables in your agent's description or notes
5. Test variables by checking server logs for "FINAL PROCESSED PROMPT"

API Reference

Hello Message Structure

interface HelloMessage {
  t: "hello";                    // Message type
  v?: number;                    // SDK version (2 for v2)
  variables?: {                   // Optional variables object
    [key: string]: string;        // Variable name -> value mapping
  };
  inputFormat?: AudioFormat;     // Input audio format
  requestedOutputFormat?: AudioFormat; // Output audio format
  outputFrameDurationMs?: number; // Frame duration for streaming
}

interface AudioFormat {
  encoding: "pcm" | "pcmu" | "pcma";
  sampleRate: number;
  channels: number;
  bitDepth: number;
  container?: "raw" | "wav";      // For output format only
}

Troubleshooting

Variables Not Being Replaced

1. Check variable names match exactly (case-sensitive)
2. Verify variables are sent in hello message (check logs)
3. Check server logs for "FINAL PROCESSED PROMPT" to see actual replacement

Variables Not in Hello Message

• SDK v2: Check if SDK supports variables in constructor
• Raw WebSocket: Ensure variables field is included in JSON
• Check WebSocket message is sent after connection opens

Default Variables Not Used

• Verify variables are stored in Redis (check agent configuration)
• Check extractVariablesFromAgentConfig is working
• Look for "Default variables not found in state" warnings in logs

Events & Callbacks

The SDK emits events for all important state changes and interactions.

Event Categories

Connection Events

voiceSDK.on('connected', () => {
  console.log('✅ Connected to agent');
});

voiceSDK.on('disconnected', (event) => {
  console.log('❌ Disconnected:', event.reason);
  console.log('Close code:', event.code);
});

voiceSDK.on('error', (error) => {
  console.error('Error:', error);
});

Recording Events

voiceSDK.on('recordingStarted', () => {
  console.log('🎤 Recording started');
});

voiceSDK.on('recordingStopped', () => {
  console.log('⏹️ Recording stopped');
});

Message Events

voiceSDK.on('message', (msg) => {
  switch(msg.type) {
    case 'agent_response':
      console.log('Agent:', msg.agent_response);
      break;
    case 'transcription':
      console.log('You said:', msg.text);
      break;
    // ... other message types
  }
});

Audio Events

voiceSDK.on('playbackStarted', () => {
  console.log('🔊 Audio playback started');
});

voiceSDK.on('playbackStopped', () => {
  console.log('🔇 Audio playback stopped');
});

voiceSDK.on('audioData', (audioData) => {
  // Raw audio data (Uint8Array)
});

Special Events

// Barge-in (user interrupts agent)
voiceSDK.on('bargeIn', (message) => {
  console.log('User interrupted the agent');
});

// Format negotiation (v2 protocol only)
voiceSDK.on('formatNegotiated', (format) => {
  console.log('Format negotiated:', format);
  // format: { container, encoding, sampleRate, channels, bitDepth }
});

// Greeting audio
voiceSDK.on('greetingStarted', () => {
  console.log('Playing greeting message');
});

// Domain whitelist error
voiceSDK.on('domainError', (error) => {
  console.error('Domain not whitelisted:', error.reason);
});

Protocol v2 - Format Negotiation

The SDK v2 introduces format negotiation, allowing you to specify exactly what audio format you want to receive from the server.

Supported Formats

Input Formats (What SDK Sends)

Output Formats (What SDK Receives)

Format Negotiation Flow

Example: High-Quality Audio

const voiceSDK = new VoiceSDK({
  signedUrl: signedUrl,  // signedUrl from backend
  appId: 'your_app_id',
  agentId: 'agent_123',
  
  // Request high-quality audio
  outputContainer: 'raw',        // Raw PCM for lower latency
  outputEncoding: 'pcm',         // Uncompressed PCM
  outputSampleRate: 48000,       // 48kHz for high quality
  outputBitDepth: 16,            // 16-bit depth
  outputChannels: 1,             // Mono
  outputFrameDurationMs: 600,    // 600ms frames
  
  protocolVersion: 2             // Enable format negotiation
});

voiceSDK.on('formatNegotiated', (format) => {
  console.log('Negotiated format:', format);
  // If backend sends different format, SDK will convert automatically
});

Example: Bandwidth-Optimized Audio

const voiceSDK = new VoiceSDK({
  signedUrl: signedUrl,  // signedUrl from backend
  appId: 'your_app_id',
  agentId: 'agent_123',
  
  // Request compressed, low-bandwidth audio
  outputContainer: 'raw',
  outputEncoding: 'pcmu',        // μ-law compression (8kHz equivalent)
  outputSampleRate: 8000,        // 8kHz for bandwidth savings
  outputBitDepth: 16,
  outputChannels: 1,
  
  protocolVersion: 2
});

Format Conversion

If the backend sends audio in a different format than requested, the SDK automatically converts it:

• Container: WAV ↔ Raw PCM extraction/wrapping
• Encoding: PCM ↔ PCMU/PCMA encoding/decoding
• Sample Rate: Automatic resampling using Web Audio API
• Bit Depth: 8-bit ↔ 16-bit ↔ 24-bit conversion
• Channels: Mono/stereo conversion (if needed)

Voice & Chat Widget

Pre-built, customizable widget with voice and text chat - perfect for adding AI conversation to any website.

Installation

<!-- Add the SDK script to your page -->
<script src="https://unpkg.com/ttp-agent-sdk/dist/agent-widget.js"></script>

<!-- Initialize the widget -->
<script>
  const widget = new TTPAgentSDK.TTPChatWidget({
    agentId: 'agent_123',
    appId: 'your_app_id'
  });
</script>

Basic Configuration

const widget = new TTPAgentSDK.TTPChatWidget({
  // Required
  agentId: 'agent_123',       // Your AI agent ID
  appId: 'your_app_id',       // Your application ID
  
  // Optional - Signed URL (recommended for production)
  signedUrl: 'wss://speech.talktopc.com/ws/conv?signed_token=...', // Signed URL from your backend
  
  // Optional - Agent Settings Override (requires signed URL with allowOverride=true)
  agentSettingsOverride: {
    prompt: "You are a helpful customer service assistant.",
    temperature: 0.8,
    voiceId: "F2",
    voiceSpeed: 1.2,
    firstMessage: "Hello! How can I help you today?",
    disableInterruptions: false,
    maxCallDuration: 600
  },
  
  // Optional - Appearance
  primaryColor: '#7C3AED',    // Widget theme color
  position: 'bottom-right',   // 'bottom-right', 'bottom-left'
  language: 'en',             // 'en', 'es', 'fr', 'de', 'he', etc.
  direction: 'ltr',           // 'ltr' or 'rtl' for right-to-left languages
  
  // Optional - Variables
  variables: {
    userName: 'John Doe',
    page: 'homepage',
    customData: 'value'
  }
});

Signed Link Authentication (Production)

To use signed links with the widget, provide a signedUrl parameter. You should fetch this signed URL from your backend before initializing the widget:

// Step 1: Get signed URL from your backend
async function initializeWidget() {
  // Request signed URL from your backend
  const response = await fetch('/api/get-voice-session', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getAuthToken()}` // Your auth token
    },
    body: JSON.stringify({
      agentId: 'agent_123',
      appId: 'your_app_id',
      variables: {
        userName: 'John Doe',
        page: 'homepage'
      }
    })
  });
  
  if (!response.ok) {
    throw new Error(`Backend API error: ${response.status}`);
  }
  
  const data = await response.json();
  
  // Backend must return signedUrl field
  if (!data.signedUrl) {
    throw new Error('Backend response must contain "signedUrl" field');
  }
  
  // Step 2: Initialize widget with signedUrl
  const widget = new TTPAgentSDK.TTPChatWidget({
    agentId: 'agent_123',
    appId: 'your_app_id',
    signedUrl: data.signedUrl,  // Use signed URL from backend
    variables: {
      userName: 'John Doe',
      page: 'homepage'
    }
  });
}

// Initialize when ready
initializeWidget();

Backend Implementation Example

Your backend endpoint should request signed URLs from TTP:

// Your Backend (Node.js/Express example)
app.post('/api/get-voice-session', async (req, res) => {
  const { agentId, appId, variables } = req.body;
  
  // Authenticate your user
  if (!req.user) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  // Backend-to-Backend: Request signed URL from TTP
  const response = await fetch('https://backend.talktopc.com/api/public/agents/signed-url', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.TTP_API_KEY}` // Your TTP API key
    },
    body: JSON.stringify({
      agentId,
      appId,
      variables
    })
  });
  
  if (!response.ok) {
    return res.status(500).json({ error: 'Failed to get signed URL' });
  }
  
  const data = await response.json();
  
  // Return signedUrl to frontend
  res.json({
    signedUrl: data.signedUrl
  });
});

Advanced Customization

Icon Customization

const widget = new TTPAgentSDK.TTPChatWidget({
  agentId: 'agent_123',
  appId: 'your_app_id',
  
  icon: {
    type: 'custom',                              // 'default', 'emoji', or 'custom'
    customImage: 'https://your-site.com/logo.png', // Custom image URL
    size: 60,                                    // Icon size in pixels
    backgroundColor: '#FFFFFF',                  // Background color
    borderRadius: '50%'                         // Border radius (50% for circle)
  }
});

Chat Window Customization

const widget = new TTPAgentSDK.TTPChatWidget({
  agentId: 'agent_123',
  appId: 'your_app_id',
  
  chatWindow: {
    width: 400,                    // Width in pixels
    height: 600,                   // Height in pixels
    title: 'Chat with us!',        // Custom title
    subtitle: 'We reply instantly', // Custom subtitle
    placeholder: 'Type here...',   // Input placeholder
    borderRadius: 12               // Window border radius
  }
});

Branding

const widget = new TTPAgentSDK.TTPChatWidget({
  agentId: 'agent_123',
  appId: 'your_app_id',
  
  branding: {
    companyName: 'Your Company',
    logo: 'https://your-site.com/logo.png',
    showPoweredBy: false           // Hide "Powered by TTP" footer
  }
});

Agent Settings Override

Dynamically customize agent behavior, voice, and personality on a per-session basis:

const widget = new TTPAgentSDK.TTPChatWidget({
  agentId: 'agent_123',
  appId: 'your_app_id',
  signedUrl: 'wss://speech.talktopc.com/ws/conv?signed_token=...', // Required: signed URL with allowOverride=true
  
  // Override agent settings dynamically
  agentSettingsOverride: {
    // Core settings
    prompt: "You are a friendly customer service assistant",
    temperature: 0.8,
    maxTokens: 200,
    
    // Voice settings
    voiceId: "F2",
    voiceSpeed: 1.2,
    
    // Behavior
    firstMessage: "Hello! How can I help you today?",
    disableInterruptions: false,
    maxCallDuration: 600,
    
    // Language
    language: "en",
    autoDetectLanguage: false
  }
});

See the Agent Settings Override section for complete documentation of all available override settings.

RTL (Right-to-Left) Support

// For Hebrew, Arabic, etc.
const widget = new TTPAgentSDK.TTPChatWidget({
  agentId: 'agent_123',
  appId: 'your_app_id',
  direction: 'rtl',
  language: 'he',                  // Hebrew
  position: 'bottom-left'          // Better for RTL
});

Widget Methods

// Open chat from your own button
document.getElementById('myButton').onclick = () => {
  widget.open();
};

widget.close();

widget.toggle();

widget.destroy();

widget.updateConfig({
  primaryColor: '#FF5733',
  language: 'es'
});

Widget Events

const widget = new TTPAgentSDK.TTPChatWidget({
  agentId: 'agent_123',
  appId: 'your_app_id',
  
  // Event callbacks
  onOpen: () => {
    console.log('Chat opened');
  },
  
  onClose: () => {
    console.log('Chat closed');
  },
  
  onMessage: (message) => {
    console.log('New message:', message);
  },
  
  onError: (error) => {
    console.error('Widget error:', error);
  },
  
  onReady: () => {
    console.log('Widget initialized');
  }
});

Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website with AI Chat</title>
</head>
<body>
  <h1>Welcome to my website!</h1>
  
  <!-- Load the SDK -->
  <script src="https://unpkg.com/ttp-agent-sdk/dist/agent-widget.js"></script>
  
  <!-- Initialize widget -->
  <script>
    const widget = new TTPAgentSDK.TTPChatWidget({
      agentId: 'agent_123',
      appId: 'your_app_id',
      
      // Customize appearance
      primaryColor: '#7C3AED',
      position: 'bottom-right',
      language: 'en',
      
      // Custom branding
      chatWindow: {
        title: 'Chat with us!',
        subtitle: 'We typically reply instantly'
      },
      
      // Pass context variables
      variables: {
        userName: 'Visitor',
        page: window.location.pathname,
        referrer: document.referrer
      },
      
      // Event handlers
      onReady: () => {
        console.log('Chat widget ready!');
      },
      
      onMessage: (message) => {
        // Track messages in analytics
        console.log('Message:', message);
      }
    });
    
    // Optional: Open chat programmatically
    // widget.open();
  </script>
</body>
</html>

Configuration Reference

See the live demo to experiment with all customization options interactively.

📖 Tip: All configuration options support the spread operator (...), so you can pass additional custom properties that will be merged with defaults.

Use Cases

Vanilla JavaScript Guide

Use the SDK in any JavaScript application without frameworks.

Complete Example

import { VoiceSDK } from 'ttp-agent-sdk';

class VoiceAssistant {
  constructor() {
    this.sdk = null;
    this.isConnected = false;
    this.isRecording = false;
  }

  async initialize(agentId, overrides = {}) {
    // Step 1: Get signed URL
    const signedUrl = await this.getSignedUrl(agentId);

    // Step 2: Create SDK
    this.sdk = new VoiceSDK({
      signedUrl: signedUrl,  // signedUrl from backend
      appId: 'your_app_id',
      agentId: agentId,
      agentSettingsOverride: overrides
    });

    // Setup event listeners
    this.setupEventListeners();

    // Connect
    await this.sdk.connect();
  }

  setupEventListeners() {
    this.sdk.on('connected', () => {
      this.isConnected = true;
      this.updateUI('connected');
    });

    this.sdk.on('disconnected', () => {
      this.isConnected = false;
      this.isRecording = false;
      this.updateUI('disconnected');
    });

    this.sdk.on('recordingStarted', () => {
      this.isRecording = true;
      this.updateUI('recording');
    });

    this.sdk.on('recordingStopped', () => {
      this.isRecording = false;
      this.updateUI('connected');
    });

    this.sdk.on('message', (msg) => {
      if (msg.type === 'agent_response') {
        this.displayMessage('agent', msg.agent_response);
      }
    });

    this.sdk.on('error', (error) => {
      this.handleError(error);
    });
  }

  async getSignedUrl(agentId) {
    const response = await fetch('/api/get-voice-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        agentId: agentId
      })
    });
    
    const { signedUrl } = await response.json();
    return signedUrl;
  }

  async toggleRecording() {
    if (!this.isConnected) return;

    if (this.isRecording) {
      await this.sdk.stopRecording();
    } else {
      await this.sdk.startRecording();
    }
  }

  disconnect() {
    if (this.sdk) {
      this.sdk.disconnect();
      this.sdk = null;
    }
  }

  updateUI(state) {
    // Update your UI based on state
  }

  displayMessage(role, text) {
    // Display message in your UI
  }

  handleError(error) {
    // Handle errors
  }
}

// Usage
const assistant = new VoiceAssistant();

await assistant.initialize('agent_123', {
  language: 'es',
  temperature: 0.9
});

React Integration

Use the SDK in React applications with hooks and components.

Using Hooks

import React, { useState, useEffect, useRef } from 'react';
import { VoiceSDK } from 'ttp-agent-sdk';

function VoiceChat() {
  const [status, setStatus] = useState('disconnected');
  const [isRecording, setIsRecording] = useState(false);
  const [messages, setMessages] = useState([]);
  const sdkRef = useRef(null);

  // Initialize SDK
  useEffect(() => {
    async function initSDK() {
      // Get signed URL
      const response = await fetch('/api/get-voice-session', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          agentId: 'agent_123'
        })
      });
      
      const { signedUrl } = await response.json();

      // Create SDK
      const sdk = new VoiceSDK({
        signedUrl: signedUrl,  // signedUrl from backend
        appId: 'your_app_id',
        agentId: 'agent_123',
        agentSettingsOverride: {
          language: 'es',
          temperature: 0.9
        }
      });

      // Event listeners
      sdk.on('connected', () => setStatus('connected'));
      sdk.on('disconnected', () => {
        setStatus('disconnected');
        setIsRecording(false);
      });
      sdk.on('recordingStarted', () => setIsRecording(true));
      sdk.on('recordingStopped', () => setIsRecording(false));
      sdk.on('message', (msg) => {
        if (msg.type === 'agent_response') {
          setMessages(prev => [
            ...prev,
            { role: 'agent', text: msg.agent_response }
          ]);
        }
      });

      await sdk.connect();
      sdkRef.current = sdk;
    }

    initSDK();

    // Cleanup
    return () => {
      if (sdkRef.current) {
        sdkRef.current.disconnect();
      }
    };
  }, []);

  const toggleRecording = async () => {
    if (sdkRef.current) {
      await sdkRef.current.toggleRecording();
    }
  };

  return (
    <div>
      <div>Status: {status}</div>
      <button onClick={toggleRecording} disabled={status !== 'connected'}>
        {isRecording ? 'Stop' : 'Start'} Recording
      </button>
      <div>
        {messages.map((msg, i) => (
          <div key={i}>{msg.role}: {msg.text}</div>
        ))}
      </div>
    </div>
  );
}

export default VoiceChat;

VoiceButton Component

Pre-built React component for quick integration.

Installation

import { VoiceButton } from 'ttp-agent-sdk/react';

Basic Usage

import React, { useState, useEffect } from 'react';
import { VoiceButton } from 'ttp-agent-sdk/react';

function App() {
  const [signedUrl, setSignedUrl] = useState(null);

  useEffect(() => {
    async function fetchSignedUrl() {
      const response = await fetch('/api/get-voice-session', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          agentId: 'agent_123'
        })
      });
      
      const { signedUrl } = await response.json();
      setSignedUrl(signedUrl);
    }
    
    fetchSignedUrl();
  }, []);

  if (!signedUrl) return <div>Loading...</div>;

  return (
    <VoiceButton
      signedUrl={signedUrl}  {/* signedUrl from backend */}
      appId="your_app_id"
      agentId="agent_123"
      agentSettingsOverride={{
        language: 'es',
        temperature: 0.9
      }}
      onConnected={() => console.log('Connected')}
      onMessage={(msg) => console.log('Message:', msg)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

Props

Event Callbacks

VoiceSDK Class

Core class for voice interaction functionality.

Constructor

new VoiceSDK(config)

Configuration Object

Audio Format Configuration (v2 Protocol)

The SDK v2 supports format negotiation with the backend. You can specify both input and output audio formats:

Example: Custom Audio Format

const voiceSDK = new VoiceSDK({
  signedUrl: signedUrl,  // signedUrl from backend
  appId: 'your_app_id',
  agentId: 'agent_123',
  
  // Input format (what we send to server)
  sampleRate: 16000,
  channels: 1,
  bitDepth: 16,
  
  // Output format (what we want from server)
  outputContainer: 'raw',        // 'raw' or 'wav'
  outputEncoding: 'pcm',          // 'pcm', 'pcmu', 'pcma'
  outputSampleRate: 44100,       // Higher quality
  outputChannels: 1,
  outputBitDepth: 16,
  outputFrameDurationMs: 600,    // Frame duration for streaming
  
  // Protocol version
  protocolVersion: 2              // Use v2 protocol for format negotiation
});

// Listen for format negotiation
voiceSDK.on('formatNegotiated', (format) => {
  console.log('Format negotiated:', format);
  // format contains: { container, encoding, sampleRate, channels, bitDepth }
});

Methods

await voiceSDK.connect();

voiceSDK.disconnect();

await voiceSDK.startRecording();

await voiceSDK.stopRecording();

await voiceSDK.toggleRecording();

const status = voiceSDK.getStatus();
// Returns: {
//   version: '2.0.0',
//   isConnected: boolean,
//   isRecording: boolean,
//   isPlaying: boolean,
//   outputFormat: object,      // Negotiated output format (v2)
//   audioPlayer: object,       // AudioPlayer status
//   audioRecorder: object      // AudioRecorder status
// }

const error = voiceSDK.validateInputFormat({
  encoding: 'pcm',
  sampleRate: 16000,
  bitDepth: 16,
  channels: 1
});
if (error) {
  console.error('Invalid format:', error);
}

const error = voiceSDK.validateOutputFormat({
  container: 'raw',
  encoding: 'pcm',
  sampleRate: 44100,
  bitDepth: 16,
  channels: 1
});
if (error) {
  console.error('Invalid format:', error);
}

voiceSDK.updateConfig({
  outputSampleRate: 48000,
  outputEncoding: 'pcmu'
});

await voiceSDK.reconnect();

voiceSDK.stopAudioPlayback();

voiceSDK.on('connected', () => {
  console.log('Connected!');
});

voiceSDK.destroy();

Events Reference

Configuration Options

Agent Settings Override

Complete reference for all overridable settings:

Core Settings

Voice Settings

Behavior Settings

Advanced Settings

Text-to-Speech API

PUBLIC REST API

Generate high-quality voice audio from text using our public REST API endpoint.

Endpoint

POST https://backend.talktopc.com/api/public/agents/tts/generate

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Parameters

Example Requests

curl -X POST https://backend.talktopc.com/api/public/agents/tts/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "text": "Hello! Welcome to our service.",
    "voiceId": "nova",
    "voiceSpeed": 1.2,
    "language": "en"
  }' \
  --output speech.mp3

const response = await fetch('https://backend.talktopc.com/api/public/agents/tts/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.TTP_API_KEY}`
  },
  body: JSON.stringify({
    text: 'Hello! Welcome to our service.',
    voiceId: 'nova',
    voiceSpeed: 1.2,
    language: 'en'
  })
});

// Response is audio file
const audioBuffer = await response.arrayBuffer();
const audioBlob = new Blob([audioBuffer], { type: 'audio/mpeg' });

// Play or save the audio
const audioUrl = URL.createObjectURL(audioBlob);
const audio = new Audio(audioUrl);
audio.play();

import requests
import os

url = "https://backend.talktopc.com/api/public/agents/tts/generate"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['TTP_API_KEY']}"
}
data = {
    "text": "Hello! Welcome to our service.",
    "voiceId": "nova",
    "voiceSpeed": 1.2,
    "language": "en"
}

response = requests.post(url, json=data, headers=headers)

if response.status_code == 200:
    # Save audio to file
    with open("speech.mp3", "wb") as f:
        f.write(response.content)
    print("Audio saved to speech.mp3")
else:
    print(f"Error: {response.status_code}")

<?php
$url = "https://backend.talktopc.com/api/public/agents/tts/generate";
$apiKey = getenv('TTP_API_KEY');

$data = [
    'text' => 'Hello! Welcome to our service.',
    'voiceId' => 'nova',
    'voiceSpeed' => 1.2,
    'language' => 'en'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    file_put_contents('speech.mp3', $response);
    echo "Audio saved to speech.mp3";
} else {
    echo "Error: HTTP $httpCode";
}
?>

import java.net.http.*;
import java.net.URI;
import java.nio.file.*;

public class TTSExample {
    public static void main(String[] args) throws Exception {
        String url = "https://backend.talktopc.com/api/public/agents/tts/generate";
        String apiKey = System.getenv("TTP_API_KEY");
        
        String json = """
            {
                "text": "Hello! Welcome to our service.",
                "voiceId": "nova",
                "voiceSpeed": 1.2,
                "language": "en"
            }
            """;
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        
        HttpResponse<byte[]> response = client.send(
            request, 
            HttpResponse.BodyHandlers.ofByteArray()
        );
        
        if (response.statusCode() == 200) {
            Files.write(Paths.get("speech.mp3"), response.body());
            System.out.println("Audio saved to speech.mp3");
        } else {
            System.out.println("Error: " + response.statusCode());
        }
    }
}

Response

The endpoint returns audio data directly with the following headers:

Voice Speed Examples

Backend Implementation Example

// Your backend endpoint
app.post('/api/generate-speech', async (req, res) => {
  const { text, voiceSpeed = 1.0 } = req.body;
  
  // Call TTP TTS API
  const ttpResponse = await fetch('https://backend.talktopc.com/api/public/agents/tts/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.TTP_API_KEY}`  // 🔒 Secret!
    },
    body: JSON.stringify({
      text: text,
      voiceSpeed: voiceSpeed,
      voiceId: 'nova',
      language: 'en'
    })
  });
  
  if (!ttpResponse.ok) {
    return res.status(ttpResponse.status).json({ 
      error: 'TTS generation failed' 
    });
  }
  
  // Forward audio to client
  const audioBuffer = await ttpResponse.arrayBuffer();
  res.set('Content-Type', 'audio/mpeg');
  res.send(Buffer.from(audioBuffer));
});

Error Responses

Use Cases

Java SDK

Server-side Java SDK for text-to-speech conversion. Perfect for backend applications, phone systems, and server-to-server integrations.

Installation

Maven

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/TTP-GO/java-sdk</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.talktopc</groupId>
        <artifactId>ttp-agent-sdk-java</artifactId>
        <version>1.0.5</version>
    </dependency>
</dependencies>

<settings>
    <servers>
        <server>
            <id>github</id>
            <username>YOUR_GITHUB_USERNAME</username>
            <password>YOUR_GITHUB_TOKEN</password>
        </server>
    </servers>
</settings>

Gradle

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/TTP-GO/java-sdk")
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
            password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
        }
    }
}

dependencies {
    implementation 'com.talktopc:ttp-agent-sdk-java:1.0.5'
}

Quick Start

1. Initialize SDK

import com.talktopc.sdk.VoiceSDK;

// Get API key from environment variable
String apiKey = System.getenv("TALKTOPC_API_KEY");

VoiceSDK sdk = VoiceSDK.builder()
    .apiKey(apiKey)
    .baseUrl("https://api.talktopc.com")  // Optional
    .build();

2. Simple TTS (Blocking)

// Generate complete audio file
byte[] audio = sdk.textToSpeech("Hello world", "mamre");

// Save to file
Files.write(Paths.get("output.wav"), audio);

// Or send to phone system
phoneSystem.playAudio(audio);

3. Streaming TTS (Real-time)

// Stream audio chunks as they're generated
sdk.textToSpeechStream(
    "Hello world, this is a longer text that will be streamed",
    "mamre",
    audioChunk -> {
        // Receive chunks in real-time
        phoneSystem.playAudio(audioChunk);
    }
);

API Reference

VoiceSDK

Main SDK entry point for text-to-speech operations.

Builder Methods

Methods

TTSRequest Builder

Configure TTS requests with audio format options.

Basic Configuration

TTSRequest request = TTSRequest.builder()
    .text("Hello world")              // Required
    .voiceId("mamre")                // Required
    .speed(1.0)                      // Optional (0.1 - 3.0)
    .build();

Audio Format Configuration

TTSRequest request = TTSRequest.builder()
    .text("Hello world")
    .voiceId("mamre")
    .outputContainer("raw")          // "raw" or "wav"
    .outputEncoding("pcm")           // "pcm", "pcmu", "pcma"
    .outputSampleRate(16000)         // Hz (8000, 16000, 22050, 44100)
    .outputBitDepth(16)              // bits (8, 16, 24)
    .outputChannels(1)               // 1 (mono) or 2 (stereo)
    .outputFrameDurationMs(600)     // ms per frame (for streaming)
    .build();

Preset Methods

TTSResponse

Response object containing audio and metadata.

Examples

Basic Usage

VoiceSDK sdk = VoiceSDK.builder()
    .apiKey(System.getenv("TALKTOPC_API_KEY"))
    .build();

// Simple TTS
byte[] audio = sdk.textToSpeech("Welcome to TalkToPC", "mamre");
System.out.println("Generated " + audio.length + " bytes of audio");

// Save to file
Files.write(Paths.get("output.wav"), audio);

With Speed Control

// Faster speech (1.5x speed)
byte[] fastAudio = sdk.textToSpeech("Quick message", "mamre", 1.5);

// Slower speech (0.8x speed)
byte[] slowAudio = sdk.textToSpeech("Slow and clear", "mamre", 0.8);

Streaming with Metadata

sdk.textToSpeechStream(
    TTSRequest.builder()
        .text("Streaming example with full configuration")
        .voiceId("mamre")
        .speed(1.0)
        .build(),
    audioChunk -> {
        // Handle each audio chunk
        System.out.println("Received chunk: " + audioChunk.length + " bytes");
        phoneSystem.playAudio(audioChunk);
    },
    metadata -> {
        // Handle completion
        System.out.println("Stream completed:");
        System.out.println("  Total chunks: " + metadata.getTotalChunks());
        System.out.println("  Total bytes: " + metadata.getTotalBytes());
        System.out.println("  Duration: " + metadata.getDurationMs() + " ms");
        System.out.println("  Credits: " + metadata.getCreditsUsed());
    },
    error -> {
        // Handle errors
        System.err.println("Stream error: " + error.getMessage());
    }
);

Phone System Integration

Perfect for Twilio, Telnyx, or custom VoIP systems.

Standard Phone System (PCMU @ 8kHz)

// Using convenient phoneSystem() preset
TTSRequest request = TTSRequest.builder()
    .text("Hello, thank you for calling. How can I help you today?")
    .voiceId("en-US-female")
    .phoneSystem()  // ✅ PCMU @ 8kHz, 20ms frames
    .build();

sdk.textToSpeechStream(
    request,
    audioChunk -> {
        // audioChunk is PCMU @ 8kHz, 20ms frames (160 bytes)
        // Ready to send directly to phone connection
        phoneConnection.sendAudio(audioChunk);
    }
);

Twilio Integration

TTSRequest request = TTSRequest.builder()
    .text("Your appointment is confirmed for tomorrow at 3 PM")
    .voiceId("en-US-male")
    .outputContainer("raw")
    .outputEncoding("pcmu")      // μ-law for Twilio
    .outputSampleRate(8000)       // 8kHz
    .outputBitDepth(16)
    .outputChannels(1)            // Mono
    .outputFrameDurationMs(20)    // 20ms frames
    .build();

sdk.textToSpeechStream(
    request,
    audioChunk -> {
        // Send to Twilio Media Stream
        twilioStream.sendMedia(audioChunk);
    }
);

Custom Audio Format

TTSRequest request = TTSRequest.builder()
    .text("Custom format example")
    .voiceId("mamre")
    .outputContainer("raw")
    .outputEncoding("pcm")
    .outputSampleRate(16000)      // 16kHz
    .outputBitDepth(16)           // 16-bit
    .outputChannels(1)            // Mono
    .outputFrameDurationMs(100)   // 100ms frames
    .build();

byte[] audio = sdk.textToSpeech(request);
// Expected: 16kHz PCM, 16-bit, mono

High Quality Audio

TTSRequest request = TTSRequest.builder()
    .text("This is a high quality recording")
    .voiceId("mamre")
    .highQuality()  // WAV @ 44.1kHz
    .build();

byte[] audio = sdk.textToSpeech(request);
Files.write(Paths.get("high_quality.wav"), audio);

Error Handling

import com.talktopc.sdk.exception.TtsException;

try {
    byte[] audio = sdk.textToSpeech("Test", "mamre");
} catch (TtsException e) {
    System.err.println("TTS Error [" + e.getStatusCode() + "]: " + e.getErrorMessage());
    
    switch (e.getStatusCode()) {
        case 401:
            System.err.println("→ Invalid API key");
            break;
        case 402:
            System.err.println("→ Insufficient credits");
            break;
        case 400:
            System.err.println("→ Invalid parameters");
            break;
        default:
            System.err.println("→ Other error");
    }
}

Full Configuration Example

import com.talktopc.sdk.models.TTSRequest;
import com.talktopc.sdk.models.TTSResponse;

// Build request with all options
TTSRequest request = TTSRequest.builder()
    .text("Full configuration example")
    .voiceId("mamre")
    .speed(1.2)
    .outputContainer("wav")
    .outputEncoding("pcm")
    .outputSampleRate(44100)
    .outputBitDepth(16)
    .outputChannels(1)
    .build();

// Get response with metadata
TTSResponse response = sdk.synthesize(request);

System.out.println("Audio: " + response.getAudioSizeBytes() + " bytes");
System.out.println("Sample rate: " + response.getSampleRate() + " Hz");
System.out.println("Duration: " + response.getDurationMs() + " ms");
System.out.println("Credits: " + response.getCreditsUsed());

// Save audio
Files.write(Paths.get("output.wav"), response.getAudio());

Supported Audio Formats

Requirements

• Java 11 or higher
• Valid TalkToPC API key
• No external dependencies - Uses Java 11+ HttpClient

Resources

• GitHub Repository: TTP-GO/java-sdk
• Maven Package: com.talktopc:ttp-agent-sdk-java:1.0.5
• Documentation: See README.md in the repository
• Examples: Check src/main/java/com/talktopc/sdk/examples/