Calls

Calls represent phone conversations handled by your AI assistants. HMS Sovereign supports both inbound and outbound calls.

Calls represent phone conversations handled by your AI assistants. HMS Sovereign supports both inbound calls (someone calls your number) and outbound calls (your assistant calls someone).

Call Lifecycle

Inbound Calls

Ringing - Call comes in to your registered number
Assistant Request - If configured, webhook is called to customize the assistant
In Progress - Call is answered and conversation begins
Ended - Call ends (customer hung up, assistant ended, or transfer)
Report - End-of-call webhook sent with summary and analysis

Outbound Calls

Dialing - Assistant initiates call to destination
In Progress - Destination answers, conversation begins
Ended - Call ends
Report - End-of-call webhook sent

Call Properties

Property	Type	Description
`id`	string	Unique call identifier
`caller_phone`	string	Caller's phone number (E.164)
`agent_phone`	string	Assistant's phone number (E.164)
`status`	string	`connecting`, `in-progress`, `ended`, `failed`
`error`	string	Error message if call failed
`started_at`	datetime	When call was answered
`ended_at`	datetime	When call ended
`duration_seconds`	integer	Call duration
`summary`	string	AI-generated call summary
`assistant_name`	string	Name of assistant that handled call
`business_name`	string	Business name of assistant

Listing Calls

curl "https://api.hmsovereign.com/api/v1/calls?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "calls": [
    {
      "id": "call-_+31612345678_abc123",
      "caller_phone": "+31612345678",
      "agent_phone": "+31850835037",
      "status": "ended",
      "duration_seconds": 84,
      "summary": "Customer asked about opening hours and wanted to schedule an appointment.",
      "agent_name": "Customer Support",
      "business_name": "Acme Corp",
      "started_at": "2025-12-13T10:00:00.000Z",
      "ended_at": "2025-12-13T10:01:24.000Z",
      "created_at": "2025-12-13T09:59:55.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}

Filtering Calls

Filter by status:

curl "https://api.hmsovereign.com/api/v1/calls?status=in-progress" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by date range:

curl "https://api.hmsovereign.com/api/v1/calls?start_date=2025-12-01T00:00:00Z&end_date=2025-12-13T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

See List Calls for all parameters.

Initiating Outbound Calls

Make your assistant call someone using an existing assistant configuration:

curl -X POST https://api.hmsovereign.com/api/v1/calls/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+31612345678",
    "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "assistant_override": {
      "first_message": "Good afternoon, I'm calling from Acme to confirm your appointment.",
      "llm_config": {
        "messages": [
          {
            "role": "system",
            "content": "Customer appointment on 2025-12-15 at 14:00. This is a reminder call."
          }
        ]
      }
    }
  }'

Or create a transient assistant with full configuration:

curl -X POST https://api.hmsovereign.com/api/v1/calls/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+31612345678",
    "number_id": "e0f48fcd-21f4-4f20-a29b-46336aead8f9",
    "assistant": {
      "name": "Appointment Reminder Assistant",
      "first_message": "Good afternoon, this is a reminder for your appointment.",
      "llm_config": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "messages": [
          {
            "role": "system",
            "content": "You are a friendly appointment reminder assistant."
          }
        ]
      },
      "tts_config": {
        "provider": "elevenlabs",
        "model": "eleven_turbo_v2_5",
        "voice_id": "FpLGR2n1CcG1v7SHJFsa",
        "language": "nl"
      },
      "stt_config": {
        "provider": "deepgram",
        "model": "nova-2",
        "language": "nl"
      }
    }
  }'

Response:

{
  "success": true,
  "call_id": "call-outbound-abc123",
  "status": "dialing"
}

Outbound Call Parameters

Parameter	Required	Description
`destination`	Yes	Phone number to call (E.164 format)
`assistant_id`	Conditional	Reference to existing assistant (use with `assistant_override`)
`assistant`	Conditional	Full transient assistant configuration
`assistant_override`	No	Override specific fields when using `assistant_id`
`number_id`	Conditional	Phone number to use (required if using `assistant`)

Note: The agent_id, agent, and agent_override parameters are deprecated but still work as aliases.

Use Cases for Outbound Calls

Appointment reminders
Customer follow-ups
Survey calls
Delivery notifications
Payment reminders

See Initiate Outbound Call for details.

Real-time Call Control

Send commands to active calls. The call must have status in-progress.

Inject Context

Add information to the assistant's context without speaking:

curl -X POST https://api.hmsovereign.com/api/v1/calls/CALL_ID/control \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inject-context",
    "content": "Customer verified: John Smith, account #12345",
    "trigger_response": true
  }'

Make Assistant Speak

curl -X POST https://api.hmsovereign.com/api/v1/calls/CALL_ID/control \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "say",
    "content": "One moment please, I'm transferring you.",
    "end_after": false
  }'

End Call

curl -X POST https://api.hmsovereign.com/api/v1/calls/CALL_ID/control \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "end-call",
    "message": "Thank you for calling. Goodbye!"
  }'

Transfer Call

curl -X POST https://api.hmsovereign.com/api/v1/calls/CALL_ID/control \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transfer",
    "destination": "+31201234567",
    "message": "I'm transferring you to our sales team."
  }'

See Send Control Command to Active Call for details.

Assistants - Configure assistants that handle calls
Call Status Webhook - Receive real-time status updates
End of Call Report - Get post-call summaries

On this page