@glydeunity/voice-sdk

Customer and web developer guide for the packaged GLYDE Voice SDK.

Version: latest (see package.json)

What You Get

• Drop-in CDN widget via window.GlydeChat
• Headless clients: GlydeVoice, GlydeText
• React components/hooks for custom app UIs

CDN Widget (recommended)

Auto-init script tag

<script
  src="https://unpkg.com/@glydeunity/voice-sdk@latest/dist/glyde-chat.umd.js"
  data-publishable-key="YOUR_PUBLISHABLE_KEY"
  data-context-type="discovery"
  data-context-id="YOUR_CLIENT_UUID"
></script>

Manual init

<script src="https://unpkg.com/@glydeunity/voice-sdk@latest/dist/glyde-chat.umd.js"></script>
<script>
  GlydeChat.init({
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
    contextType: 'screening',
    contextId: 'APPLICATION_UUID',
    unityBaseUrl: 'https://api.glydeunity.com',
    displayMode: 'floating',
    defaultMode: 'voice',
    allowModeSwitch: true,
  });
</script>

Scenario Configurations (from current CDN test patterns)

1) Known Applicant

{
  contextType: 'screening',
  contextId: 'APPLICATION_UUID',
}

2) Known Candidate (Discovery)

{
  contextType: 'candidate_discover',
  contextId: 'CANDIDATE_UUID',
}

3) Job Page Visitor

{
  contextType: 'job_apply',
  contextId: 'JOB_UUID',
}

4) Unknown Visitor

{
  contextType: 'discovery',
  contextId: 'CLIENT_UUID',
}

Voice Playback Speed

Agent speech plays at 1.2x by default (20% faster). Override with playbackSpeed:

GlydeChat.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  contextType: 'screening',
  contextId: 'APPLICATION_UUID',
  playbackSpeed: 1.0,   // 1.0 = normal, 1.2 = default, range 0.7-1.5
});

Speed is applied natively by Deepgram TTS (agent.speak.provider.speed), so there is no pitch shift. Clamped to Deepgram's supported range 0.7 - 1.5. See TTS voice controls.

Language & Voice Switching (v1.10.0+)

The voice agent is bilingual (English / Spanish LatAm) by default. Unity resolves a per-language voice map (en: aura-2-thalia-en, es: aura-2-selena-es) and returns it as language_config on the auth/config responses. The SDK then:

1. Opens the session on the English-native voice (no Spanish accent on English turns).
2. Detects the language of each user turn (Flux Multilingual reports it on the transcript).
3. Swaps the TTS voice via Deepgram UpdateSpeak before the reply is synthesised, and emits a language_changed event ({ language, source: 'detection' | 'manual', voice }).

Manual control:

// Pin the agent to Spanish for the whole session (from init):
GlydeChat.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  contextType: 'screening',
  contextId: 'APPLICATION_UUID',
  languageMode: 'es',        // 'auto' (default) | 'en' | 'es'
});

// Or at runtime via the class / hook:
voice.setLanguage('auto');   // re-enable detection-driven switching
voice.setLanguage('en');     // pin to English
voice.getActiveLanguage();   // 'en' | 'es' | null
voice.getLanguageConfig();   // { languages, tts_voices, voice_switching } | null

The VoiceChat component renders an Auto / EN / ES toggle in its header whenever the server exposes a language_config, and useVoiceAgent exposes languageConfig, activeLanguage, and setLanguage.

Older Unity APIs return no language_config; the SDK then keeps the session's initial voice (English turns native, Spanish turns through the English voice). Tenants can pin a single voice server-side (unity_configuration.voice.tts_voice or voice_switching: "off"), which disables switching on the client.

Continuity Controls

Use these to tune chat history sent to the backend:

• skipContinuityLimit: true -> send full history
• limitToLast: 5 -> current CDN test behavior
• limitToLast: 50 -> long-running candidate/discovery flows

Example:

GlydeChat.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  contextType: 'screening',
  contextId: 'APPLICATION_UUID',
  skipContinuityLimit: false,
  limitToLast: 5,
});

Display Modes

• floating - launcher bubble + chat panel
• modal - overlay panel
• inline - embed directly into a container
• mobile - full viewport mobile layout

Examples:

GlydeChat.init({ ...config, displayMode: 'modal', dimensions: { width: 500, height: 600 } });
GlydeChat.render('#chat-container', { ...config, displayMode: 'inline', dimensions: { width: '100%', height: 650 } });
GlydeChat.init({ ...config, displayMode: 'mobile' });

GlydeChat Global API

• GlydeChat.init(config)
• GlydeChat.render(container, config)
• GlydeChat.destroy()
• GlydeChat.version

Script Data Attributes

Supported attributes for auto-init:

• data-publishable-key, data-api-key, data-auth-token
• data-context-type, data-context-id
• data-unity-url
• data-auto-init
• data-default-mode, data-position, data-theme
• data-display-mode, data-container-id
• data-width, data-height, data-max-width, data-max-height
• data-dimensions
• data-show-header, data-allow-close, data-allow-mode-switch

NPM Usage

npm install @glydeunity/voice-sdk

import { GlydeVoice, GlydeText, ChatWidget, useVoiceAgent, useTextChat } from '@glydeunity/voice-sdk';

Context Rules

Default behavior: if contextType is omitted, the SDK now defaults to discovery.

| Context Type | Required contextId | |---|---| | screening | application_uuid | | job_apply | job_uuid | | candidate_discover | candidate_uuid | | candidate_apply | candidate_uuid:job_uuid | | discovery | optional (client_uuid recommended) | | recruiter, custom, phone | optional |

Text mode and voice mode both use the same contextType semantics. If you are using a non-screening flow (for example discovery with a client_uuid), always pass contextType explicitly to avoid screening-only initialization paths.

Troubleshooting

• If widget does not appear, verify auth key and data-auto-init settings.
• If voice fails, ensure HTTPS and microphone permissions.
• If context errors occur, validate contextType + contextId format.
• If text mode calls /api/unity/screening/summary/* unexpectedly, ensure the text component receives the same contextType used by voice mode.