xAI Grok Integration

xAI's Grok Realtime API provides speech-to-speech conversation with <700ms latency. Unlike traditional voice AI (STT → LLM → TTS), Grok processes audio directly in a single model.

Setup

xAI Grok is available as a provider choice on HMS Sovereign's platform keys by default — you can select it when configuring an assistant without adding any API key first.

1. (Optional) Add your own xAI API Key

This step is optional, only needed to run Grok on your own xAI account. To use platform keys, skip straight to step 2. To bring your own key, navigate to Integrations → API Keys tab and add it:

curl -X POST https://api.hmsovereign.com/api/v1/byok 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "provider": "xai",
    "api_key": "xai-..."
  }'

2. Configure Assistant

When creating or editing an assistant with xAI configured:

• Provider: Select "xAI Realtime"
• Model: see the table below
• Voice: ara (or any of the 26 available voices)

Note: When using xAI Realtime, separate STT/TTS providers are ignored.

Models

grok-realtime-v1 is xAI's retired name. Assistants that still store it keep working, but do not pick it for anything new.

Tuning

Every field below is optional and lives on llm_config. Leave one out and xAI's own default applies, so an assistant you never touch keeps behaving exactly as it does today. Values outside a documented range are clamped rather than rejected, and a value of the wrong type is logged and skipped: a mistake in this block costs you the setting, never the call.

Reasoning

{ "reasoning_effort": "none" }

By default Grok reasons before it answers, on every single turn. That is what makes it good at multi-step instructions, and on a phone line it is also what the caller hears as a pause before the reply starts. Setting none removes that step.

none and high are the only two values the realtime endpoint accepts. Effort levels you may know from the text API (low, medium, and so on) are rejected there.

Which one is right depends on the assistant. A receptionist that routes calls and takes messages rarely needs reasoning. An assistant that has to weigh conditions, follow a policy or interpret an ambiguous request usually does.

Speaking speed

{ "speed": 0.95 }

Playback speed of the assistant's voice, between 0.7 and 1.5. Slightly below 1.0 tends to help on older phone lines and with elderly callers.

Picking the conversation back up

{ "turn_detection": { "idle_timeout_ms": 8000 } }

When set, xAI re-opens the conversation itself after this much silence, instead of both sides waiting. The timer re-arms after every reply, so a caller who keeps going quiet gets prompted again each time. Leave it out and nothing happens on silence.

Keep it generous. A caller who is looking something up needs seconds, not milliseconds, and an assistant that jumps in too early reads as impatient. Anything under a second is raised to one second, and xAI caps the value at thirty seconds.

Getting names right in the transcript

{
  "transcription": {
    "language_hint": "nl",
    "keyterms": ["VoiceDock", "Flireo"]
  }
}

This biases the transcription of what the caller says. It shapes the transcript and everything downstream of it, so the post-call analysis and any structured data you extract improve along with it.

keyterms is for the words a transcriber has no way to guess: brand names, product names, street names, jargon from your trade. At most 100 entries of 50 characters. language_hint steers recognition towards one language; an unrecognised code is ignored and detection falls back to automatic.

Tools xAI runs itself

{
  "provider_tools": [
    "web_search",
    { "type": "x_search", "allowed_x_handles": ["voicedock"] },
    { "type": "file_search", "vector_store_ids": ["your-collection-id"], "max_num_results": 10 }
  ]
}

These run on xAI's servers during the call. There is no webhook to answer and no handler to write: the assistant searches, gets its result and carries on talking. They are additive, so your own tools in llm_config.tools keep working alongside them.

All three need your own xAI key. xAI charges per invocation on top of the per-minute rate: $5 per 1,000 searches for web and X, $2.50 per 1,000 for collections. VoiceDock bills per minute, so there is no line on your invoice where those charges could go. On your own key they land in your own xAI account, which is where they belong. Configure them on a platform key and they are skipped: the assistant still takes the call, it just cannot look anything up. Add your key under Integrations first.

file_search searches an xAI collection, which is the shortest route to a knowledge base an assistant can quote from. It needs at least one collection id; without one the tool is dropped. It is tied to your own key twice over, because a collection only exists inside the account it was created in.

Pricing

• Platform keys (default): xAI model usage at cost + €0,07/min orchestration. No API key setup needed.
• Bring Your Own Key (optional): €0,07/min orchestration, with xAI API usage billed directly to your own xAI account and no markup on it.

Per-minute rates are xAI's list prices and cover speech recognition, the model and speech synthesis together, so no separate STT or TTS cost applies.

Differences from Traditional Mode

Limitations

• A prompt written for another model is usually longer than Grok needs. Its own guidance is to shorten it and to strip instructions that only existed to work around an older model.
• Voice selection is limited to xAI's 26 voices.
• Two features from xAI's own API documentation are not available through VoiceDock, because the client library we run does not send them: pronunciation replacements (replace) and conversation resumption after a dropped connection (resumption).

API Reference

See BYOK API Reference for managing xAI API keys.