VoiceDock Docs
Getting Started

Quickstart

Create your first AI voice assistant and make it available on a phone number in minutes.

This guide walks you through creating your first AI voice assistant and making it available on a phone number.

Prerequisites

  • An HMS Sovereign account with an API key
  • A phone number configured to forward calls to HMS Sovereign (contact support for SIP configuration)

Step 1: Get Your API Key

Find your API key in the dashboard under Settings > API Keys. You'll use this for all API requests.

Step 2: Create an Assistant

Create a new AI assistant with a simple POST request:

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",
    "business_name": "Acme Corp",
    "first_message": "Hello, welcome to Acme. How can I help you?",
    "llm_config": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "temperature": 0.7,
      "messages": [
        {
          "role": "system",
          "content": "You are a friendly customer service agent for Acme Corp. Answer questions about opening hours, products and services. Be helpful and professional."
        }
      ]
    },
    "stt_config": {
      "provider": "deepgram",
      "model": "nova-3-general",
      "language": "en"
    },
    "tts_config": {
      "provider": "openai",
      "voice_id": "alloy",
      "language": "en"
    }
  }'

Response:

{
  "assistant": {
    "id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "name": "Customer Support Assistant",
    "business_name": "Acme Corp",
    "first_message": "Hello, welcome to Acme. How can I help you?",
    "is_active": true,
    "stt_config": { ... },
    "llm_config": { ... },
    "tts_config": { ... },
    "created_at": "2025-12-13T10:00:00.000Z",
    "updated_at": "2025-12-13T10:00:00.000Z"
  }
}

Save the id - you'll need it to assign a phone number.

Step 3: Register a Phone Number

Register your phone number and assign the assistant:

curl -X POST https://api.hmsovereign.com/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+31850835037",
    "name": "Main Support Line",
    "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88"
  }'

Response:

{
  "number": {
    "id": "abc12345-1234-5678-9012-abcdef123456",
    "phone_number": "+31850835037",
    "name": "Main Support Line",
    "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "created_at": "2025-12-13T10:05:00.000Z"
  }
}

Step 4: Test Your Assistant

Call the phone number you registered. Your assistant will answer and greet the caller with the configured first message.

Step 5: View Call History

After the call, view it in your call history:

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

Response:

{
  "calls": [
    {
      "id": "call-_+31612345678_abc123",
      "caller_phone": "+31612345678",
      "assistant_phone": "+31850835037",
      "status": "ended",
      "duration_seconds": 45,
      "summary": "Customer asked about opening hours.",
      "assistant_name": "Customer Support Assistant",
      "created_at": "2025-12-13T10:10:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0
  }
}

Next Steps

Introduction

VoiceDock is a voice AI platform powered by HMS Sovereign v1. Build AI voice assistants that handle phone calls, execute custom functions, and integrate with your applications.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

On this page

PrerequisitesStep 1: Get Your API KeyStep 2: Create an AssistantStep 3: Register a Phone NumberStep 4: Test Your AssistantStep 5: View Call HistoryNext Steps