Documentation

Getting started

Dragon PBX requires three external services: a Drachtio SIP server, RTPEngine for media, and Redis for state. Configuration is done through environment variables and a config file or API.

# Core dependencies
DRACHTIO_HOST=localhost
DRACHTIO_PORT=9022
RTPENGINE_HOST=localhost
RTPENGINE_PORT=2223

# Choose a configuration backend
DATA_SOURCE=json   # or: api, pg

Configuration

Domains

The top-level grouping. Each domain is identified by its FQDN and contains its own clients and trunks.

Clients

SIP endpoints that register to the system. Defined by a username pattern — 1??? matches any 4-digit extension starting with 1, * matches everything.

Each client has a RegHook URL for authentication or can use a static password and dialplan for simpler setups.

Trunks

SIP connections to external providers. Inbound traffic is matched by source IP (CIDR notation). Outbound calls are sent to a configured host with optional authentication.

Trunks with outbound credentials will automatically maintain SIP registrations with the provider.

Dialplans

A mapping of dialled number patterns to CallHook URLs. Patterns support ? for a single digit and * for multiple digits.

{
  "1???": "https://example.com/internal",
  "0*": "https://example.com/external",
  "9": "https://example.com/operator"
}

Webhook reference

RegHook

Request: POST with SIP digest auth fields, source IP/port, and requested expiry.

Response: Return {"status": "ok"} with a dialplan and optional codecs to accept the registration, or a non-200 status to reject.

CallHook

Request: POST with domain, from, to, callId, sourceAddress, source (client or trunk), refer flag, and count.

Response: A JSON array of CallScript verbs.

StatusHook

Receives: POST notifications with callId, event, and optional label. Events include connect:trying, connect:answered, connect:hangup, playback:start, playback:complete, and others.

Verb reference

announce

Play audio to the caller.

Param	Type	Description
url	string	file:// path to a wav file

connect

Connect the call to one or more destinations.

Param	Type	Description
dest	array	Destinations to ring in parallel
dest[].type	string	client, trunk, or sip
dest[].address	string	Extension number, SIP URI, or trunk number
dest[].timeout	int	Ring timeout in seconds
dest[].trunk_id	int	Trunk ID (for type=trunk)
dest[].trunk_name	string	Trunk name (for type=trunk)
reconnect	bool	Re-offer to new destinations if already connected
statusLabel	string/bool	Label for status events, or false to suppress

response

Send a SIP response code to end the call.

Param	Type	Description
code	int	SIP response code (3xx–6xx)
headers	object	Additional SIP headers

pause

Delay processing.

Param	Type	Description
duration	int	Seconds to wait

record

Fork call audio to a SIPREC recording server (RFC 7865/7866). Place it before a connect; recording starts automatically when that call answers and stops when the call ends. Best-effort — if the recorder is unreachable the call is unaffected.

Param	Type	Description
siprecServer	string	SIP URI of the recording server (required)
legs	string	Which legs to record: a, b, or both (default)
codec	string/array	Force the recorded stream to a codec (e.g. PCMU)
from	string	Override the From header on the SIPREC INVITE
proxy	string	Outbound proxy for the SIPREC INVITE
auth	object	{username, password} for digest auth to the recorder
headers	object	Additional SIP headers on the SIPREC INVITE
metadata	object	Participant names and custom session metadata

pickup

Answer a call ringing at (or connected to) another extension and bridge its remote party to the caller. Matches by extension within the caller's domain.

Param	Type	Description
target	string/array	Extension(s) to pick up; a list is tried in order (pickup groups)
state	string	ringing (default) — grab a ringing call; connected — grab a live call

Environment variables

Full list of configuration options:

Variable	Default	Description
DRACHTIO_HOST	localhost	Drachtio SIP server host
DRACHTIO_PORT	9022	Drachtio connection port
DRACHTIO_SECRET	cymru	Drachtio shared secret
RTPENGINE_HOST	same as Drachtio	RTPEngine host
RTPENGINE_PORT	2223	RTPEngine control port
DATA_SOURCE	api	Config backend: json, api, or pg
CONFIG_URL	—	URL for API backend
CONFIG_TOKEN	—	Bearer token for API backend
CONFIG_TTL	60	API config cache TTL (seconds)
DEFAULT_CODECS	G722, PCMA, PCMU	Default codec list
DEFAULT_RINGTONE	file:/uk.wav	Default ringback tone
LOGLEVEL	debug	Log level
WEBPORT	2999	HTTP API port
REGISTRATION_MIN_SECS	30	Minimum registration expiry
REGISTRATION_MAX_SECS	3600	Maximum registration expiry

Source code

Dragon PBX is available on GitHub.