Initiate outbound call

Initiate an outbound call from an AI assistant to a destination phone number.

Phone Number Selection (Important for Resellers):

You can specify which phone number to call from using the number_id parameter. This is highly recommended for:

Resellers: Ensure calls are made from numbers dedicated to specific clients

Branding: Always use the same caller ID for recognition

Compliance: Meet legal requirements for specific numbers

Local presence: Use local numbers for better answer rates

If number_id is not provided, the system will automatically select an available number from your organization's pool, which may not be appropriate for reseller scenarios where numbers are client-specific.

Three Usage Modes:

Reference Mode (assistant_id)

Reference an existing assistant from your dashboard

Uses the assistant's pre-configured settings

Simplest option for standard calls

Transient Mode (assistant)

Create a one-time assistant configuration without saving

Full control over STT/LLM/TTS configuration

Perfect for personalized or context-specific calls

Hybrid Mode (assistant_id + assistant_override)

Reference a saved assistant as the base

Override specific fields (e.g., first_message, llm_config.messages)

Best for personalization while keeping base config

⚠️ Deprecated: agent_id, agent, and agent_config are deprecated. Use assistant_id, assistant, and assistant_override instead.

Use Cases:

Appointment reminders with personalized greetings

Customer follow-ups with dynamic context

Survey calls with specific question flows

Delivery notifications

Payment reminders with account-specific details

Configuration Notes:

When using xai_realtime provider, omit stt_config and tts_config (handled internally)

For other providers (openai, mistral), both stt_config and tts_config are required

The call will be initiated immediately and the response will include a call_id to track progress

Response Time: Your call will typically connect within 2-5 seconds.

curl --location --request POST 'https://api.hmsovereign.com/api/v1/calls/outbound' \ --header 'Content-Type: application/json' \ --data-raw '{ "destination": "+31612345678", "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88" }'

Request

Responses