Introduction

VoiceDock is our voice AI platform. HMS Sovereign v1 is the current generation model powering it — and this API is how you build with it.

Welcome! Build powerful AI voice assistants that can handle phone calls, execute custom functions, and integrate seamlessly with your applications.

HMS Sovereign v1 enables you to create intelligent voice assistants that understand natural language, execute custom functions, and provide human-like conversational experiences over the phone.

What is HMS Sovereign?

HMS Sovereign is a voice AI platform that allows you to:

• Create AI Voice Assistants - Build intelligent assistants with custom personalities and instructions

• Handle Phone Calls - Receive and make calls with natural conversation flow

• Execute Custom Functions - Let assistants perform actions via webhooks and tool calls

• Analyze Conversations - Get structured insights from call transcripts

• Integrate Anywhere - Connect with your existing systems via REST API and webhooks

• Assistants - Create and manage AI voice assistants

  • Calls - Monitor and control active calls
  • Webhooks - Receive real-time events
  • Phone Numbers - Connect your phone numbers
  • Usage - Track usage and billing
  • BYOK - Bring your own API keys

Authentication

All API requests require authentication using an API key in the Authorization header.

cURL

curl https://api.hmsovereign.com/api/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.hmsovereign.com/api/v1/assistants', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Python

import requests

response = requests.get(
  'https://api.hmsovereign.com/api/v1/assistants',
  headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

PHP

$ch = curl_init('https://api.hmsovereign.com/api/v1/assistants');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer YOUR_API_KEY'
]);
$response = curl_exec($ch);

Warning: Keep your API key secure. Never expose it in client-side code or public repositories.

Get Your API Key:

1. Sign up at hmsovereign.com
2. Navigate to Settings → API Keys
3. Generate a new API key
4. Store it securely in your environment variables

Quick Start

Get your first AI voice assistant running in 5 minutes.

Create an Assistant

Create your first AI voice assistant with the Create Assistant endpoint.

curl -X POST https://api.hmsovereign.com/api/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Assistant",
    "system_prompt": "You are a helpful customer support assistant. Be friendly and professional."
  }'

Response:

Add a Phone Number

Connect a SIP phone number to your assistant using the Register Number endpoint.

{
  "number": "+31201234567",
  "assistant_id": "agent_abc123"
}

Set Up Webhooks (Optional)

Configure webhooks in your assistant to receive real-time events and execute custom functions.

{
  "webhook_url": "https://your-domain.com/webhook",
  "webhook_events": ["tool-calls", "end-of-call-report"]
}

See Webhooks Documentation for details.

Test Your Assistant

Call your configured phone number to test the assistant. You can also use the Create Outbound Call endpoint for outbound calls.

Core Concepts

Assistants

Assistants are the foundation of HMS Sovereign. Each assistant has:

• System Prompt - Instructions that define the assistant's personality and behavior
• LLM Configuration - Language model settings (provider, model, temperature)
• TTS Configuration - Text-to-speech settings (provider, voice, speed)
• Tools - Custom functions the assistant can execute during calls
• Analysis Plan - Structured data extraction from call transcripts

View Assistant Endpoints →

Calls

Calls represent phone conversations handled by your assistants. Track:

• Real-time status updates
• Complete transcripts
• Function calls executed
• Call duration and costs
• Analysis results

View Call Endpoints →

Webhooks

Webhooks enable real-time integration with your systems. Receive events for:

• Assistant Request - Override assistant config before call starts
• Tool Calls - Execute custom functions during calls
• Status Updates - Get notified of call state changes
• End of Call Report - Receive complete call summary

**Tip: ** Always verify webhook signatures to ensure requests come from HMS Sovereign. See webhook security documentation.

API Architecture

graph TD
    Client[Your Application] -->|REST API| API[HMS Sovereign API]
    API -->|Create/Update| Assistant[AI Assistant]
    Phone[Phone Call] --> Assistant
    Assistant -->|Webhook| Client
    Assistant -->|LLM Request| LLM[Language Model]
    Assistant -->|TTS Request| TTS[Text-to-Speech]
    LLM --> Assistant
    TTS --> Phone
    Assistant -->|Store| DB[(Database)]

Key Features

Bring Your Own Key (BYOK)

Use your own API keys for LLM providers (OpenAI), STT providers (Deepgram), TTS providers (ElevenLabs), and email (Resend).

Benefits:

• Cost control
• Custom rate limits
• Access to your provider's latest features
• Data sovereignty

Configure BYOK →

Custom Tools & Functions

Define custom functions that your assistant can call during conversations.

Example Use Cases:

• Check appointment availability
• Look up order status
• Transfer to human assistant
• Create support tickets

Learn More →

Structured Analysis

Extract structured data from call transcripts using custom JSON schemas.

Example:

{
  "customer_sentiment": "positive",
  "appointment_scheduled": true,
  "follow_up_needed": false,
  "tags": ["billing", "resolved"]
}

Call Controls

Control active calls programmatically:

• Inject context mid-call
• Say custom messages
• End calls
• Transfer to SIP destinations

View Call Control API →

Rate Limits

Current Limits:

• 100 requests per minute per API key
• 10 call control commands per minute per active call

Note: Rate limits are applied per API key. Response headers include X-RateLimit-Remaining and X-RateLimit-Reset for tracking usage.

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: system_prompt",
    "param": "system_prompt",
    "type": "validation_error"
  }
}

Common HTTP Status Codes:

Webhooks Security

Always verify webhook signatures to prevent spoofing:

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, timestamp, signature, secret) {
  const sigHex = signature.replace(/^sha256=/, '');
  const message = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(sigHex),
    Buffer.from(expected)
  );
}

// Usage
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString();
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhookSignature(rawBody, timestamp, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
});

Python

import hmac
import hashlib

def verify_webhook_signature(payload: str, timestamp: str, signature: str, secret: str) -> bool:
    sig_hex = signature.removeprefix("sha256=")
    message = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig_hex, expected)

# Usage in Flask
@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.get_data(as_text=True)
    timestamp = request.headers.get('X-Webhook-Timestamp')
    signature = request.headers.get('X-Webhook-Signature')

    if not verify_webhook_signature(payload, timestamp, signature, WEBHOOK_SECRET):
        return {'error': 'Invalid signature'}, 401

    # Process webhook...

Best Practices

• System Prompts - ✅ Be specific and clear

  ✅ Define expected behavior

  ✅ Include examples

  ✅ Set boundaries

  ❌ Don't be vague

  ❌ Avoid contradictions

• Webhook Handlers - ✅ Respond within 5 seconds

  ✅ Process asynchronously

  ✅ Implement retries

  ✅ Log all attempts

  ❌ Don't perform heavy processing

  ❌ Don't ignore signatures

• Error Handling - ✅ Handle all error codes

  ✅ Use exponential backoff

  ✅ Log errors properly

  ✅ Monitor error rates

  ❌ Don't retry indefinitely

  ❌ Don't ignore rate limits

• Security - ✅ Store API keys securely

  ✅ Verify webhook signatures

  ✅ Use HTTPS everywhere

  ✅ Rotate keys regularly

  ❌ Never expose keys in code

  ❌ Don't skip validation

Need Help?

Documentation

• Assistant Configuration
• Phone Numbers Setup
• Webhook Integration
• BYOK Configuration

Support

• Email: support@hmsovereign.com
• Live Docs: doc.hmsovereign.com
• Dashboard: hmsovereign.com

Resources

• API Reference
• OpenAPI Spec
• GitHub Examples (Coming Soon)

What's Next?

Explore Assistant Endpoints

Learn how to create and configure AI assistants

View Assistant API →

Set Up Phone Numbers

Connect your SIP provider and start receiving calls

View Phone Numbers API →

Integrate Webhooks

Build real-time integrations with your systems

View Webhook Events →

Configure BYOK

Use your own API keys for LLM, STT, TTS, and email

Learn About BYOK →

Ready to build? Get your API key and create your first assistant in minutes!