quickstart

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:

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

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:

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

Configure webhooks to receive real-time call events

Add custom tools to to let your assistant look up information

Set up BYOK to use your own API keys

Enable call analysis for structured post-call data

Prerequisites#

Step 1: Get Your API Key#

Step 2: Create an Assistant#

Step 3: Register a Phone Number#

Step 4: Test Your Assistant#

Step 5: View Call History#

Next Steps#

Prerequisites

Step 1: Get Your API Key

Step 2: Create an Assistant

Step 3: Register a Phone Number

Step 4: Test Your Assistant

Step 5: View Call History

Next Steps