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 Developer > Your API Key. 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.

Note: The stt_config, llm_config, and tts_config providers above (Deepgram, OpenAI, and any other supported provider) run on HMS Sovereign's platform keys by default — you don't need to set up any API keys to create a working assistant. Bring Your Own Key is optional, for when you'd rather use your own provider accounts.

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 built by Flireo B.V., running on our own HMS Sovereign orchestration engine. Build AI voice assistants that handle phone calls, run custom functions, and integrate with your stack.

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