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

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:

Filter by date range:

See List Calls for all parameters.

Initiating Outbound Calls

Make your assistant call someone using an existing assistant configuration:

Or create a transient assistant with full configuration:

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`)

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:

Make Assistant Speak

End Call

Transfer Call

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

Call Lifecycle#

Inbound Calls#

Outbound Calls#

Call Properties#

Listing Calls#

Filtering Calls#

Initiating Outbound Calls#

Outbound Call Parameters#

Use Cases for Outbound Calls#

Real-time Call Control#

Inject Context#

Make Assistant Speak#

End Call#

Transfer Call#

Related#

Call Lifecycle

Inbound Calls

Outbound Calls

Call Properties

Listing Calls

Filtering Calls

Initiating Outbound Calls

Outbound Call Parameters

Use Cases for Outbound Calls

Real-time Call Control

Inject Context

Make Assistant Speak

End Call

Transfer Call

Related