demarcDocs

Configuration#

demarc reads its runtime configuration from .env. Restart the runtime and dashboard after changing values.

Before you start#

  • A completed local installation.
  • A private password manager or secret store.
  • Provider accounts only for the live features you intend to enable.

Core settings#

Configure these groups before production:

  • Service: a public HTTPS PUBLIC_BASE_URL, runtime URL and data location.
  • Dashboard authentication: DEMARC_WEB_PASSWORD, a distinct DEMARC_SESSION_SECRET, and a distinct DEMARC_LOGIN_FINGERPRINT_SECRET. Optionally set DEMARC_WEB_USERNAME.
  • Runtime authentication: replace the example runtime authentication token with a long random value.
  • Telephony: Telnyx API and public keys, the TeXML application and connection identifiers, TELNYX_TEXML_ACCOUNT_SID, the messaging profile, and the owned phone number.
  • Voice providers: configure live speech-to-text, language-model and text-to-speech credentials. Fake providers are for local testing only.
  • Operator routing: the destination used for captured-message notification.
  • Retention: choose transcript, message and operational retention periods that match your privacy obligations.

Do not reuse a secret between the dashboard session, login fingerprint and runtime authentication settings. Do not put credentials in browser-visible environment variables.

Phone-system settings#

Every phone-system capability ships disabled. Each flag below defaults to false, and the runtime refuses to start when a capability is enabled without its prerequisites, so enable one stage at a time and restart after each change.

Setting Enables Also requires
PHASE3_PHONE_SYSTEM_ENABLED The phone-system surface The gate for every setting below
PHASE3_CARRIER_MUTATIONS_ENABLED Provider-side changes Phone system
PHASE3_WEBRTC_CREDENTIALS_ENABLED Browser credentials Carrier mutations
PHASE3_WEBRTC_JWT_ENABLED Browser registration Credentials
PHASE3_WEBRTC_OUTBOUND_ENABLED Outbound browser calls JWT registration and PHASE2_CALL_CONTROL_ENABLED
PHASE3_WEBRTC_INBOUND_ENABLED Inbound browser ringing JWT registration
PHASE3_INBOUND_ADVANCED_ENABLED Conference-first inbound controls Inbound ringing and PHASE1_IDENTITY_ENABLED
PHASE3_VOICEMAIL_ENABLED Shared voicemail capture Identity and carrier mutations
PHASE3_QUEUES_ENABLED Call queues Inbound ringing and voicemail
PHASE3_CONFERENCE_ENABLED Two-call conference controls Outbound browser calls or inbound advanced controls
PHASE3_RECORDING_ENABLED Call recording Outbound browser calls or inbound advanced controls, plus a recording policy version and disclosure

The browser-phone rollout is a chain: credentials, then JWT registration, then inbound or outbound calling. Inbound ringing is independent of outbound authorisation but still needs the credential and JWT stack.

Before enabling PHASE3_WEBRTC_INBOUND_ENABLED, give the pilot number softphone routing, an explicit route to one enabled extension whose browser owner holds a ready registration, and a live browser presence. If ownership is missing or more than one endpoint matches, the call falls back to the configured AI experience instead of ringing a browser.

Inbound advanced controls, voicemail and queues use TeXML and need TELNYX_TEXML_ACCOUNT_SID, TELNYX_TEXML_APP_ID, TELNYX_PUBLIC_KEY and PHONE_AUTHORIZATION_SIGNING_SECRET; the runtime reports which value is missing and refuses to start without them. Voicemail and queues do not require PHASE2_CALL_CONTROL_ENABLED. Enabling inbound advanced controls does not upgrade calls already running on the basic dial path.

Recording settings#

Setting Default Purpose
PHONE_RECORDING_POLICY_VERSION Empty The policy version an operator attests to before recording
PHONE_RECORDING_DISCLOSURE_TEXT Empty The notice shown to the operator, who must confirm it before recording starts
PHONE_RECORDING_RETENTION_DAYS 30 Days a recording stays retrievable, between 1 and 365
PHONE_RECORDING_MEDIA_HOSTS api.telnyx.com,recordings.telnyx.com Exact HTTPS hosts allowed to serve inbound recording and voicemail media

Important: recording stays unavailable until both a policy version and disclosure text are set. The runtime refuses to start with PHASE3_RECORDING_ENABLED=true and either value empty.

Warning demarc does not read PHONE_RECORDING_DISCLOSURE_TEXT to participants. It is shown in the dashboard and recorded with the operator's attestation only. Announcing the recording to everyone on the call remains the operator's responsibility, and setting this value does not by itself satisfy a two-party-consent requirement.

PHONE_RECORDING_MEDIA_HOSTS accepts a comma-separated list of exact public DNS names. Wildcards, IP addresses, URLs, ports and internal names are rejected at startup; there is no bucket-wide or storage-account-wide authorisation. An empty list blocks inbound recording and voicemail playback.

Scope and limits#

  • Voicemail mailboxes are shared within one organisation. They are not personal mailboxes, and read state applies to everyone with access.
  • Queue member selection supports longest-idle and round-robin only. Saved legacy ring-all configuration is neither imported nor executed.
  • Queue member calls use the basic incoming browser media controls, so transfer, merge and recording panels are not offered on those legs.
  • The dashboard keypad is not offered on conference-backed or inbound-bound legs, so DTMF cannot be sent from those calls. It remains available on basic and outbound browser calls.
  • Recording and voicemail retention run independently of call-history retention.
  • Not available: transcription, voicemail email delivery, ring-all distribution, external or PSTN queue members, extension no-answer attachment, and managed conference room execution.

Verify#

Set DEMARC_URL to the deployed HTTPS origin, then request readiness:

if (-not $env:DEMARC_URL) { throw 'Set DEMARC_URL to the deployed origin' }
Invoke-RestMethod "$env:DEMARC_URL/api/ready"

The readiness response should be healthy before live traffic is routed to the service. Authenticated operators can also inspect /api/ops/status for schema, call-slot, scheduler and retention state.

A configuration mistake in the phone-system chain appears as a startup failure naming the missing flag or value, not as a runtime warning. Read the runtime log after each change.