Assistants

Assistants are AI-powered voice entities that handle phone conversations, each with its own personality, knowledge, and capabilities.

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. Currently powered by Deepgram.

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

Field	Description
`provider`	STT provider (`deepgram`)
`model`	Model name (e.g., `nova-3-general`)
`language`	Language code (e.g., `nl`, `en`)
`keyterms`	Optional array of words to boost recognition accuracy

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": []
  }
}

Field	Description
`provider`	LLM provider (`openai`, `mistral`, `xai`, `xai_realtime`)
`model`	Model name (e.g., `gpt-4o-mini`, `claude-3-sonnet`)
`temperature`	Response randomness (0-2, default 0.7)
`messages`	System prompts defining assistant behavior
`tools`	Custom tools the assistant can use (see Custom 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:

Provider	Description	Access
`elevenlabs`	High-quality voice cloning and natural speech	All users
`inworld`	EU-based TTS with natural Dutch voices (Katrien, Erik)	All users

ElevenLabs Models:

Model	Description
`eleven_flash_v2_5`	Fastest, low-latency (default)
`eleven_v3`	Expressive dialogue with audio tag support
`eleven_multilingual_v2`	Best quality, multilingual
`eleven_turbo_v2_5`	Balanced speed and quality
`eleven_monolingual_v1`	English only

Eleven v3 Audio Tags: When using 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?

Common Fields:

Field	Description
`provider`	TTS provider
`voice_id`	Voice identifier (snake_case)
`language`	Language code (e.g., `nl`, `en`)
`model`	Model name (provider-specific)

ElevenLabs-specific:

Field	Description
`stability`	Voice consistency (0-1, default 0.5)
`similarity_boost`	Voice similarity to original (0-1, default 0.75)
`use_speaker_boost`	Enhance speaker clarity (boolean)
`speed`	Speech speed multiplier
`style`	Speaking style intensity (0-1)

Assistant Properties

Property	Type	Description
`id`	UUID	Unique identifier (auto-generated)
`name`	string	Display name for the assistant
`business_name`	string	Business the assistant represents
`notification_email`	email	Email for call notifications
`first_message`	string	Initial greeting when call starts
`is_active`	boolean	Whether assistant can handle calls
`voicemail_detection`	boolean	Automatically detect voicemail
`voicemail_message`	string	Message to leave on voicemail
`max_duration_seconds`	number	Maximum call duration (null = unlimited)
`autonomous_silence_handling`	boolean	Auto-detect silence and prompt caller
`webhook_url`	URL	Endpoint for webhook events
`webhook_secret`	string	Secret for signature verification
`webhook_events`	array	Events to send to webhook
`analysis_plan`	object	Post-call analysis configuration

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.

List All Assistants
Get an Assistant
Phone Numbers - Assign assistants to phone numbers
Webhooks - Configure event notifications

On this page