Initiate outbound call

Initiate an outbound call from an AI agent 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 (agent_id)

Reference an existing agent from your dashboard

Uses the agent's pre-configured settings

Simplest option for standard calls

Transient Mode (agent)

Create a one-time agent configuration without saving

Full control over STT/LLM/TTS configuration

Perfect for personalized or context-specific calls

Hybrid Mode (agent_id + agent_override)

Reference a saved agent as the base

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

Best for personalization while keeping base config

⚠️ Deprecated: agent_config is deprecated. Use agent instead for transient configurations.

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, anthropic, groq), 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.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

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

Request

Responses