Introduction

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

📞

HMS Sovereign 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

JavaScript

Python

PHP

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

Get Your API Key:

Navigate to Settings → API Keys

Generate a new API key

Store it securely in your environment variables

export HMS_SOVEREIGN_API_KEY=your_api_key_here

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.

Response:

Agent

Add a Phone Number

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

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

You need to configure SIP forwarding with your provider to route calls to HMS Sovereign. See the Phone Numbers section for details.

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.

Start with a simple system prompt and iterate based on real call data

Core Concepts

Assistants

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

LLM Configuration - Language model settings with system messages that define behavior

TTS Configuration - Text-to-speech settings (provider, voice_id, speed)

STT Configuration - Speech-to-text settings (provider, language, keyterms)

Tools - Custom functions the assistant can execute during calls

Analysis Plan - Structured data extraction from call transcripts

Agent

View Assistant Endpoints →

The /api/v1/agents endpoint is deprecated but still works as an alias for /api/v1/assistants.

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

Call

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

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

API Architecture

Key Features

Bring Your Own Key (BYOK)

Custom Tools & Functions

Structured Analysis

Call Controls

Rate Limits

Current Limits:

100 requests per minute per API key

10 call control commands per minute per active call

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

Implement exponential backoff when approaching rate limits to maintain reliability

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:

Code	Description
`401 Unauthorized`	Invalid or missing API key
`400 Bad Request`	Malformed request body or parameters
`403 Forbidden`	Permission denied
`404 Not Found`	Resource doesn't exist
`409 Conflict`	Resource already exists (e.g., phone number)
`500 Server Error`	Internal server error

Implement exponential backoff for rate limit errors

Don't retry authentication errors - check your API key instead

Webhooks Security

Always verify webhook signatures to prevent spoofing:

Node.js

Python

Use timing-safe comparison functions to prevent timing attacks

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?

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!

What is HMS Sovereign?#

Authentication#

Quick Start#

Core Concepts#

Assistants#

Calls#

Webhooks#

API Architecture#

Key Features#

Rate Limits#

Error Handling#

Webhooks Security#

Best Practices#

Need Help?#

Documentation#

Support#

Resources#

What's Next?#

What is HMS Sovereign?

Authentication

Quick Start

Core Concepts

Assistants

Calls

Webhooks

API Architecture

Key Features

Rate Limits

Error Handling

Webhooks Security

Best Practices

Need Help?

Documentation

Support

Resources

What's Next?