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

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.