# 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

```json
{
  "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`