Softphone and VoIP device management API with SIP credentials, call history, and push notifications

Introduction

The Device API manages softphone devices, SIP credentials, call history, and push notification tokens for VoIP applications. It provides secure credential storage with encryption and supports multiple authentication methods.

Authentication

The Device API supports three authentication methods:

Device Management

GET /api/devices

List all registered devices.

Parameters

Parameter	Type	Description
status	string	active, inactive, all
platform	string	ios, android, web

Response

{
  "success": true,
  "data": [
    {
      "id": "dev_abc123",
      "device_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "iPhone 15 Pro",
      "platform": "ios",
      "os_version": "17.2",
      "app_version": "2.1.0",
      "status": "active",
      "has_credentials": true,
      "push_token_set": true,
      "last_seen_at": "2024-01-22T14:00:00Z",
      "created_at": "2024-01-01T10:00:00Z"
    }
  ]
}

POST /api/devices

Register a new device.

Request Body

{
  "device_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "iPhone 15 Pro",
  "platform": "ios",
  "os_version": "17.2",
  "app_version": "2.1.0",
  "device_model": "iPhone15,2",
  "push_token": "apns_token_here"
}

GET /api/devices/{id}

Get device details.

Response

{
  "success": true,
  "data": {
    "id": "dev_abc123",
    "device_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "iPhone 15 Pro",
    "platform": "ios",
    "os_version": "17.2",
    "app_version": "2.1.0",
    "device_model": "iPhone15,2",
    "status": "active",
    "settings": {
      "ringtone": "default",
      "vibration": true,
      "auto_answer": false
    },
    "sip_credentials": {
      "configured": true,
      "provider": "provider_001"
    },
    "last_seen_at": "2024-01-22T14:00:00Z"
  }
}

SIP Credentials

GET /api/devices/{id}/credentials

Retrieve SIP credentials for a device.

Parameters

Parameter	Type	Description
include_password	boolean	Include decrypted password (requires HMAC auth)

Response

{
  "success": true,
  "data": {
    "sip_server": "sip.voip-provider.com",
    "sip_port": 5060,
    "transport": "TLS",
    "username": "user123",
    "password": "********",
    "auth_username": "auth_user123",
    "display_name": "John Doe",
    "outbound_proxy": "proxy.voip-provider.com",
    "stun_server": "stun.voip-provider.com",
    "turn_server": "turn.voip-provider.com",
    "codecs": ["opus", "g711a", "g711u"]
  }
}

PUT /api/devices/{id}/credentials

Set or update SIP credentials for a device.

Request Body

{
  "sip_server": "sip.voip-provider.com",
  "sip_port": 5060,
  "transport": "TLS",
  "username": "user123",
  "password": "secret_password",
  "auth_username": "auth_user123",
  "display_name": "John Doe",
  "outbound_proxy": "proxy.voip-provider.com",
  "codecs": ["opus", "g711a"]
}

Device Settings

GET /api/devices/{id}/settings

Get device settings.

Response

{
  "success": true,
  "data": {
    "ringtone": "default",
    "vibration": true,
    "auto_answer": false,
    "auto_answer_delay": 3,
    "call_waiting": true,
    "do_not_disturb": false,
    "dnd_schedule": null,
    "voicemail_notification": true,
    "call_recording": false
  }
}

PUT /api/devices/{id}/settings

Update device settings.

Request Body

{
  "auto_answer": true,
  "auto_answer_delay": 5,
  "do_not_disturb": true,
  "dnd_schedule": {
    "start": "22:00",
    "end": "07:00",
    "days": ["Mon", "Tue", "Wed", "Thu", "Fri"]
  }
}

Call History

GET /api/devices/{id}/call-history

Get call history for a device.

Parameters

Parameter	Type	Description
direction	string	inbound, outbound, missed
from_date	date	Filter by date
limit	integer	Results per page (default: 50)

Response

{
  "success": true,
  "data": [
    {
      "id": "call_001",
      "direction": "inbound",
      "caller_number": "+33612345678",
      "caller_name": "John Doe",
      "callee_number": "+33687654321",
      "status": "answered",
      "duration_seconds": 185,
      "started_at": "2024-01-22T10:30:00Z",
      "answered_at": "2024-01-22T10:30:05Z",
      "ended_at": "2024-01-22T10:33:10Z",
      "recording_url": null
    },
    {
      "id": "call_002",
      "direction": "missed",
      "caller_number": "+33698765432",
      "caller_name": null,
      "status": "missed",
      "duration_seconds": 0,
      "started_at": "2024-01-22T11:00:00Z"
    }
  ]
}

POST /api/devices/{id}/call-history

Record a call in history.

Request Body

{
  "direction": "outbound",
  "caller_number": "+33687654321",
  "callee_number": "+33612345678",
  "callee_name": "Support",
  "status": "answered",
  "duration_seconds": 120,
  "started_at": "2024-01-22T14:00:00Z",
  "ended_at": "2024-01-22T14:02:00Z"
}

Push Tokens

PUT /api/devices/{id}/push-token

Update push notification token for incoming call notifications.

Request Body

{
  "push_token": "fcm_or_apns_token_here",
  "push_type": "apns",
  "voip_token": "apns_voip_token_for_callkit"
}

SIP Providers (Admin)

GET /api/sip-providers

List configured SIP providers.

Response

{
  "success": true,
  "data": [
    {
      "id": "provider_001",
      "name": "VoIP Provider A",
      "sip_server": "sip.provider-a.com",
      "sip_port": 5060,
      "transport": "TLS",
      "default_codecs": ["opus", "g711a"],
      "is_default": true,
      "is_active": true
    }
  ]
}

POST /api/sip-providers

Add a new SIP provider configuration.

Request Body

{
  "name": "VoIP Provider B",
  "sip_server": "sip.provider-b.com",
  "sip_port": 5061,
  "transport": "TLS",
  "outbound_proxy": "proxy.provider-b.com",
  "stun_server": "stun.provider-b.com",
  "turn_server": "turn.provider-b.com",
  "turn_username": "turn_user",
  "turn_password": "turn_pass",
  "default_codecs": ["opus", "g722"],
  "is_active": true
}

API Keys (Admin)

GET /api/api-keys

List API keys.

Response

{
  "success": true,
  "data": [
    {
      "id": "key_001",
      "name": "Mobile App Production",
      "key": "dk_live_****",
      "permissions": ["devices:read", "devices:write", "calls:read"],
      "rate_limit": 1000,
      "is_active": true,
      "last_used_at": "2024-01-22T14:00:00Z"
    }
  ]
}

POST /api/api-keys

Create a new API key.

Request Body

{
  "name": "New Mobile App Key",
  "permissions": ["devices:read", "devices:write", "calls:read", "calls:write"],
  "rate_limit": 500
}

Error Codes

Code	Status	Description
DEVICE_NOT_FOUND	404	Device does not exist
INVALID_SIGNATURE	401	HMAC signature validation failed
TIMESTAMP_EXPIRED	401	Request timestamp too old (5 min window)
CREDENTIALS_REQUIRED	400	SIP credentials not configured
PROVIDER_NOT_FOUND	404	SIP provider not found