Assistants

Assistants are AI-powered voice entities that handle phone conversations. Each assistant has its own personality, knowledge, and capabilities defined through configuration.

Note: The /api/v1/agents endpoint is deprecated but still works as an alias for /api/v1/assistants. Similarly, agent_id works as an alias for assistant_id in API requests.

Assistant Components

An assistant consists of three main AI components:

Speech-to-Text (STT)

Converts the caller's speech to text. Supported providers: deepgram, elevenlabs (Scribe), gladia, and mistral (Voxtral). All run on HMS Sovereign's platform keys by default — no API key setup required.

{
  "stt_config": {
    "provider": "deepgram",
    "model": "nova-3-general",
    "language": "en",
    "keyterms": ["yes", "no", "okay"]
  }
}

Mistral (Voxtral)

Two models under stt_config.provider: mistral:

{
  "stt_config": {
    "provider": "mistral",
    "model": "voxtral-mini-transcribe-realtime-2602"
  }
}

See Provider pricing for the rates.

Language Model (LLM)

The brain of your assistant. Processes the conversation and generates responses.

{
  "llm_config": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "messages": [
      {
        "role": "system",
        "content": "You are a friendly customer service agent..."
      }
    ],
    "tools": []
  }
}

xAI Text Models: The xai provider gives you access to Grok text models (e.g. grok-4-1-fast-non-reasoning) and uses the same API key as xai_realtime. Unlike xai_realtime, it operates as a standard text LLM and requires separate STT and TTS configuration.

Text-to-Speech (TTS)

Converts the assistant's text responses to speech.

{
  "tts_config": {
    "provider": "elevenlabs",
    "model": "eleven_flash_v2_5",
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "language": "nl",
    "stability": 0.5,
    "similarity_boost": 0.75,
    "use_speaker_boost": true
  }
}

Available Providers: All run on HMS Sovereign's platform keys by default — no API key setup required.

ElevenLabs Models:

Audio Tags: When using eleven_v4_turbo, eleven_v4 or eleven_v3, the LLM can insert audio tags in square brackets to control the emotional delivery of speech. For example, [sad], [laughing], [whispering], [cheerfully], or [cautiously]. Structure your system prompt to instruct the LLM to insert these tags before or within sentences. Example: [cheerfully] Welcome back! How can I help you today?

Settings on v4 and v3: eleven_v4_turbo, eleven_v4 and eleven_v3 take stability and apply_text_normalization. The other ElevenLabs fields (similarity_boost, style, speed, use_speaker_boost, apply_language_text_normalization) apply to the other models; saving one of them on these three returns a 400. See ElevenLabs Eleven v4.

VoiceDock voice (beta)

VoiceDock's own voice, running on our own GPU servers in the EU. The text your assistant speaks is not sent to a third-party speech provider, and it is available on every account without a key.

{
  "tts_config": {
    "provider": "voicedock",
    "model": "voicedock-1",
    "voice_id": "voicedock"
  }
}

There is one voice, voicedock. It follows the language of each reply and keeps the same voice in Dutch, English, German and French, so language does not need to be set. It has no tuning fields. It is billed per character; see Provider pricing.

The voice is in beta: it may still change based on what we hear from you. When it leaves the beta, provider, model and voice_id stay the same, so your configuration does not change.

Common Fields:

ElevenLabs-specific:

Assistant Properties

Creating an Assistant

Only the name is required. All other fields have sensible defaults.

Minimal assistant:

curl -X POST https://api.hmsovereign.com/api/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Assistant"}'

Full assistant:

curl -X POST https://api.hmsovereign.com/api/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant",
    "business_name": "Acme Corp",
    "notification_email": "support@acme.com",
    "first_message": "Hello, welcome to Acme. How can I help you?",
    "is_active": true,
    "voicemail_detection": true,
    "voicemail_message": "You've reached Acme Corp. We'll call you back shortly.",
    "max_duration_seconds": 600,
    "autonomous_silence_handling": true,
    "webhook_url": "https://api.example.com/webhooks/hms-sovereign",
    "webhook_secret": "your-secret-here",
    "webhook_events": ["end-of-call-report", "tool-calls"],
    "stt_config": {
      "provider": "deepgram",
      "model": "nova-3-general",
      "language": "en",
      "keyterms": ["yes", "no", "okay"]
    },
    "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."
        }
      ]
    },
    "tts_config": {
      "provider": "elevenlabs",
      "model": "eleven_flash_v2_5",
      "voice_id": "21m00Tcm4TlvDq8ikWAM",
      "language": "en",
      "stability": 0.5,
      "similarity_boost": 0.75,
      "use_speaker_boost": true
    }
  }'

See Create a New Assistant for complete API documentation.

Updating an Assistant

Use PATCH to update specific fields. Only provided fields are updated.

curl -X PATCH https://api.hmsovereign.com/api/v1/assistants/ASSISTANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_message": "Good afternoon, you're speaking with Acme support.",
    "is_active": false
  }'

See Update an Assistant for details.

Deleting an Assistant

When you delete an assistant, any phone numbers assigned to it will have their assistant_id set to null.

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

See Delete an Assistant for details.

Related

• Prompting per Model - What to write in the system prompt for the model this assistant runs on
• List All Assistants
• Get an Assistant
• Phone Numbers - Assign assistants to phone numbers
• Webhooks - Configure event notifications