Phone Numbers

Phone numbers are the entry point for your AI assistants. When a call comes in to a registered number, the assigned assistant handles the conversation.

How It Works

You configure a phone number with your SIP provider to forward calls to HMS Sovereign

You register the number in HMS Sovereign via the API

You assign an assistant to the number

Incoming calls are automatically handled by the assigned assistant

Phone Number Properties

Property	Type	Description
`id`	UUID	Unique identifier
`phone_number`	string	Phone number in E.164 format (e.g., `+31850835037`)
`name`	string	Display name for the number
`assistant_id`	UUID	Assigned assistant (nullable)
`transfer_trunk_id`	UUID	SIP trunk for call transfers (nullable)

Registering a Phone Number

Response:

{
  "number": {
    "id": "abc12345-1234-5678-9012-abcdef123456",
    "phone_number": "+31850835037",
    "name": "Main Support Line",
    "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "transfer_trunk_id": null,
    "created_at": "2025-12-13T10:00:00.000Z",
    "updated_at": "2025-12-13T10:00:00.000Z"
  }
}

See Register a Phone Number for details.

Updating Assistant Assignment

Change which assistant handles calls for a number:

To unassign an assistant (calls will not be handled):

See Update a Phone Number for details.

Configuring Call Transfers

To enable call transfers from this number, assign a SIP trunk:

See SIP Trunks for trunk configuration.

Listing All Numbers

Response:

{
  "numbers": [
    {
      "id": "abc12345-...",
      "phone_number": "+31850835037",
      "name": "Main Support Line",
      "assistant_id": "17a0cb75-...",
      "transfer_trunk_id": null
    },
    {
      "id": "def67890-...",
      "phone_number": "+31201234567",
      "name": "Sales Line",
      "assistant_id": "28b1dc86-...",
      "transfer_trunk_id": "trunk-123-..."
    }
  ]
}

See List All Phone Numbers for details.

Deleting a Phone Number

See Delete a Phone Number for details.

Assistants - Create assistants to assign to numbers

SIP Trunks - Configure trunks for call transfers

Calls - View call history for your numbers

How It Works#

Phone Number Properties#

Registering a Phone Number#

Updating Assistant Assignment#

Configuring Call Transfers#

Listing All Numbers#

Deleting a Phone Number#

Related#