1. Sdk
  • HMS Sovereign API
  • Get started
    • Authentication
    • Introduction
    • Quickstart
  • Core concepts
    • Assistants
    • Calls
    • Phone Numbers
    • Webhooks
  • Platform
    • Billing & Credits
    • EU Data Sovereignty
    • Voice Selection
    • Whitelabel Portal
  • Webhooks
    • Assistant Request
    • End of Call Report
    • Webhooks Overview
    • Webhook Security
    • Status Update
    • Tool Calls
  • Configuration
    • Analysis Templates
    • Custom Tools
    • SIP Trunks
    • Tool Templates
  • Features
    • AI Generation
    • Autonomous Silence Handling
    • Call Analysis
    • Call Transfers
    • Campaigns Setup
    • Outbound Campaigns
    • Voicemail Detection
    • Web Calls
  • Integrations
    • BYOK Setup
    • Provider Pricing
    • xAI Grok Integration
  • Reference
    • Changelog
    • Error Codes
    • Rate Limits
    • Troubleshooting
  • Sdk
    • Node.js SDK
Documentation
API Reference
Documentation
API Reference
Book a meeting
Linkedin
Github
  1. Sdk

Node.js SDK

Official TypeScript/Node.js SDK for the HMS Sovereign Voice AI Platform. Zero dependencies, full type safety, and support for all API endpoints.

Installation#

Requires Node.js 20 or later.

Quick Start#

Resources#

All resources are available as properties on the client:
ResourceDescription
client.assistantsCRUD for AI voice assistants
client.callsList calls, make outbound calls, call control
client.numbersPhone number management
client.campaignsOutbound call campaigns with leads
client.sipTrunksSIP trunk configuration
client.voicesList available TTS voices
client.usageUsage logs and billing
client.byokBring Your Own Key management
client.toolTemplatesReusable tool/function templates
client.analysisTemplatesPost-call analysis schemas
client.domainsCustom domain configuration
client.organizationsOrganization management

Outbound Calls#

Three configuration modes for outbound calls:

Reference mode — use a saved assistant#

Transient mode — one-time assistant config#

Hybrid mode — saved assistant with overrides#

The metadata object is passed through to all webhook events at message.assistant.metadata.

Call Control#

Control active calls in real-time:

Pagination#

List endpoints return a Page with metadata:

Auto-pagination#

Iterate through all results automatically with listAll():
Auto-pagination is available on client.calls.listAll() and client.usage.listAll().

Campaigns#

Run automated outbound call campaigns:

Webhook Verification#

The SDK provides built-in webhook signature verification. See Webhook Security for background.
Raw body required
You must use express.raw() (or equivalent) to get the raw request body. Parsed JSON bodies will fail signature verification because the signature is computed over the original string.

Error Handling#

The SDK throws typed errors that you can catch with instanceof:
All errors extend HmsSovereignError and include status, message, and code properties.

Configuration#

OptionDefaultDescription
apiKey—Your HMS Sovereign API key (required)
baseUrlhttps://api.hmsovereign.com/api/v1API base URL
maxRetries2Automatic retries on 5xx and 429 responses
timeout30000Request timeout in milliseconds
debugfalseLog all HTTP requests and responses to console
The SDK automatically retries failed requests with exponential backoff. On 429 responses, it respects the Retry-After header.

TypeScript#

The SDK is written in TypeScript and exports types for all resources. Import them directly:

Source & Issues#

GitHub: github.com/flireo-bv-org/hmsovereign-node
npm: npmjs.com/package/hmsovereign
Issues: github.com/flireo-bv-org/hmsovereign-node/issues
Modified at 2026-03-23 15:36:10
Previous
Troubleshooting
Built with