API Reference

1. Status Change Webhook

Sends a POST request to your configured endpoint on every status change. This is the primary integration point for real-time call monitoring, wallboards, and analytics.

Configuration

Settings > Webhook Endpoint URL: The URL to receive POST requests
Settings > Webhook API Key: Optional Bearer token for authentication

Request Format

Method: POST
Content-Type: application/json
Authorization: Bearer <API Key>
Timeout: 10 seconds
Retry: Once after 1 second on failure

Payload Example

{
  "event":         "status_change",
  "status":        "on_call",
  "direction":     "inbound",
  "remote_number": "4169987587",
  "remote_name":   "John Doe",
  "extension":     "1001",
  "call_id":       "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp":     "2026-02-17T17:48:16.0000000Z",
  "duration":      0
}

Status Values

Status	Direction	When
`available`	null	Phone registers successfully
`ringing`	inbound/outbound	Call arrives or you dial out
`on_call`	inbound/outbound	Call is answered
`hold`	inbound/outbound	Call placed on hold
`available`	inbound/outbound	Call ends (duration populated)
`offline`	null	Phone unregisters

2. CRM Lookup Integration

Automatically opens a URL in the default browser when an incoming call is answered.

URL Format

Use {phone} as a placeholder for the caller's phone number:

          https://crm.company.com/search?phone={phone}
        

The phone number is URL-encoded automatically. Special characters like +, (, ), and spaces are properly escaped.

3. Call Recording Upload

HelixPhone can automatically upload call recordings to your server via HTTP POST.

Recording Format

Format: WAV (16-bit PCM, mono, 8000 Hz)
Size: ~960 KB per minute
Filename: {TO}_{FROM}_{YYYY}_{MM}_{DD}_{HH}_{mm}_{EPOCH_MS}.wav

Upload Request

Method: POST
Content-Type: multipart/form-data
Authorization: Bearer <API Key>
Field name: file
Retry: Up to 3 attempts

4. Configuration Reference

All settings are stored in: %LOCALAPPDATA%\HelixPhone\settings.json

Full Example

{
  "Sip": {
    "Server": "sip.provider.com",
    "Port": 5060,
    "Transport": "UDP",
    "Username": "1001",
    "Password": "secret"
  },
  "Webhook": {
    "EndpointUrl": "https://your-server.com/webhook",
    "ApiKey": "your-secret"
  },
  "Recording": {
    "Enabled": true,
    "UploadUrl": "https://your-server.com/recordings",
    "ApiKey": "your-secret"
  },
  "Crm": {
    "Enabled": true,
    "LookupUrl": "https://crm.company.com/search?phone={phone}"
  }
}

Sections