explorer-monorepo/docs/specs/vtm/soul-machines-integration.md

Soul Machines Integration Specification

Overview

Integration with Soul Machines digital humans for Virtual Teller Machine (VTM) experience.

Digital Human UI Embedding

Web Integration

Method: Embed Soul Machines SDK/widget Container: React component or iframe Positioning: Modal overlay or side panel

Mobile Integration

Method: Native SDK integration UI: Full-screen or overlay

XR Integration

Method: 3D digital human in XR environment Platform: WebXR or native XR app

API Integration Points

Session Management

Endpoints:

• Create session
• End session
• Get session status

Conversation Management

Events:

• User message
• Digital human response
• Intent detection
• Workflow triggers

Session Management

Session Lifecycle

1. User initiates VTM session
2. Create Soul Machines session
3. Authenticate user (if required)
4. Load user context
5. Start conversation
6. End session (user or timeout)

Session Data

Stored:

• Session ID
• User ID
• Conversation history
• Workflow state
• Timestamps

Conversation State Persistence

State Storage

Storage: Database or session store Retention: Per session, archive after completion

State Schema

{
  "session_id": "uuid",
  "user_id": "uuid",
  "conversation_history": [...],
  "workflow_state": {...},
  "intents": [...],
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

References

• Teller Orchestrator: See teller-orchestrator.md
• Workflows: See teller-workflows.md