LLM Prompt

# VoiceRail API Reference

VoiceRail is a voice AI platform for building conversational phone agents. It uses DISC behavioral psychology for natural personality modeling and supports custom reasoning via webhooks.

## Base URLs
- API: https://api.voicerail.ai
- Voice: https://voice.voicerail.ai

## Authentication
All requests require:
- Header: `Authorization: Bearer $VOICERAIL_KEY`
- Header: `X-Organization-Id: $ORG_ID`

## Core Entities

### Assistant
A callable voice agent with personality and voice configuration.

```typescript
interface Assistant {
  name: string;                    // Human-readable name
  archetype: string;               // "helper" | "challenger" | "mentor" | "analyst" | etc.
  discProfile: {
    dominance: number;             // 0-100: Direct vs collaborative
    influence: number;             // 0-100: Enthusiastic vs reserved
    steadiness: number;            // 0-100: Patient vs dynamic
    conscientiousness: number;     // 0-100: Analytical vs big-picture
  };
  voice: {
    provider: "azure";
    voiceId: string;               // e.g., "en-US-JennyNeural"
  };
  // Optional fields:
  quickGreeting?: string;          // Short intro: "Hey, this is Alex"
  firstMessage?: string;           // First full message
  firstMessageMode?: "assistant-speaks-first" | "assistant-waits-for-user";
  endCallMessage?: string;         // Message when ending call
  endCallPhrases?: string[];       // Phrases that trigger call end
  transferDestinations?: TransferDestination[];
  personaFingerprint?: PersonaFingerprint;
  reasoningWebhook?: ReasoningWebhookConfig;
  tools?: AssistantTool[];
}

interface TransferDestination {
  phoneNumber: string;             // E.164 format
  name: string;
  description?: string;
  transferMessage?: string;
  transferMode?: "blind" | "warm-transfer-with-summary" | "warm-transfer-with-message";
}

interface PersonaFingerprint {
  stockPhrases?: string[];         // Repeated phrases (max 5)
  preferredHedges?: string[];      // "kind of", "probably" (max 5)
  acknowledgments?: string[];      // "got it", "I hear you" (max 5)
  fillerPreferences?: string[];    // "well", "so" (max 3)
  turnTakingStyle?: "questions" | "confirmations" | "mixed";
  contractionLevel?: number;       // 0-100 (0=formal, 100=very casual)
  speechRate?: number;             // -50 to +50
  pitchAdjustment?: number;        // -20 to +20
}

interface ReasoningWebhookConfig {
  url: string;
  bearerToken: string;
  timeoutSeconds?: number;
}
```

### Call
Represents a phone call with an assistant.

```typescript
interface Call {
  id: string;
  assistantId: string;
  status: "initiated" | "ringing" | "in_progress" | "completed" | "failed" | "transferred";
  toPhoneNumber: string;           // E.164 format
  fromPhoneNumber?: string;        // Caller ID
  startedAt?: string;
  endedAt?: string;
  durationSeconds?: number;
}
```

## API Endpoints

### Create Assistant
```bash
POST /v1/assistants
{
  "name": "Alex",
  "archetype": "helper",
  "discProfile": { "dominance": 45, "influence": 70, "steadiness": 60, "conscientiousness": 50 },
  "voice": { "provider": "azure", "voiceId": "en-US-JennyNeural" }
}
```

### Get Assistant
```bash
GET /v1/assistants/{id}
```

### List Assistants
```bash
GET /v1/assistants
```

### Update Assistant
```bash
PATCH /v1/assistants/{id}
{
  "name": "Updated Name",
  "discProfile": { "dominance": 60, "influence": 75, "steadiness": 50, "conscientiousness": 55 }
}
```

### Delete Assistant
```bash
DELETE /v1/assistants/{id}
```

### Make Call (Voice Service)
```bash
POST https://voice.voicerail.ai/api/v1/calls
{
  "assistantId": "asst_xxx",
  "toPhoneNumber": "+15551234567",
  "fromPhoneNumber": "+15559876543"  // Optional caller ID
}
```

### Get Call
```bash
GET /v1/calls/{id}
```

### List Calls
```bash
GET /v1/calls?assistantId=xxx&status=completed&limit=10
```

## DISC Profile Guidelines

DISC is a behavioral psychology model. Each dimension is 0-100:

- **High D (70+)**: Direct, decisive, results-focused. Use for sales, executive calls.
- **High I (70+)**: Enthusiastic, persuasive, optimistic. Use for onboarding, engagement.
- **High S (70+)**: Patient, reliable, supportive. Use for support, healthcare.
- **High C (70+)**: Analytical, precise, quality-focused. Use for technical, financial.

Common profiles:
- Sales: D=75, I=80, S=35, C=45
- Support: D=30, I=55, S=80, C=65
- Technical: D=40, I=35, S=65, C=85
- General: D=45, I=60, S=55, C=55

## Archetypes

Choose one to define base conversation patterns:
- `helper`: Supportive, service-focused
- `challenger`: Direct, challenges assumptions
- `mentor`: Patient, educational
- `analyst`: Data-driven, precise
- `counselor`: Thoughtful, advisory
- `collaborator`: Team-oriented
- `architect`: Strategic, systematic
- `storyteller`: Narrative-driven

## Azure Voice IDs

Popular options:
- `en-US-JennyNeural`: Female, conversational
- `en-US-GuyNeural`: Male, friendly
- `en-US-AriaNeural`: Female, neutral
- `en-US-DavisNeural`: Male, authoritative

## Webhooks (Optional)

If configured, your webhook receives:
```json
{
  "callId": "call_abc123",
  "utterance": "What the user said",
  "state": { "custom": "data" },
  "context": [{ "role": "user", "content": "..." }]
}
```

Return:
```json
{
  "reply": "What assistant says",
  "state": { "updated": "data" }
}
```

## Best Practices

1. Start with no webhook - VoiceRail's built-in AI works well for most cases
2. Use DISC profiles instead of complex prompts for personality
3. Keep quickGreeting under 10 words for fast call starts
4. Test on actual phones - telephony audio differs from speakers
5. Use E.164 format for all phone numbers (+15551234567)