Skip to main content

billing_step = 6

Routing, SIP Trunks, and Billing Templates

RustPBX separates transport (Trunks) from policy (Routing) and overlays billing templates for financial abstraction. This chapter walks through planning, configuration, and verification of carrier connectivity.

1. SIP Trunk management​

1.1 Modeling principles​

  • Trunk = carrier resource: represents a carrier, wholesale partner, or internal SBC including reachability, authentication, and codec capabilities.
  • Multiple trunks: orchestrate several trunks to balance cost, geography, or redundancy, and invoke them via routing priorities or round-robin strategies.

1.2 Creating a trunk​

  1. Console → SIP Trunk → New, supply the label and SIP URI (sip:host:port).
  2. Choose authentication:
    • IP allowlist: configure carrier egress IPs and permitted codecs.
    • Username/password: fill username/password and optionally enable TLS/SRTP.
  3. Fill runtime properties: codec list, max_calls, allowed inbound_hosts, direction (direction), and backup destination (backup_dest).
  4. Save to obtain a trunk_id that can be referenced from routing or billing templates.

(Insert a screenshot of the trunk form.)

1.3 GitOps configuration​

Declare trunks under config/trunks/*.toml if you manage configs in Git:

name = "carrier-a"
uri = "sip:1.2.3.4:5060"
auth = { type = "ip", cidr = ["1.2.3.4/32"] }
codecs = ["g711a", "g729", "opus"]
concurrency_limit = 200

Run a Reload after committing changes (see the Diagnostics chapter).

2. Routing strategies​

2.1 Rule structure​

FieldDescription
directioninbound or outbound; differentiates call direction
matcherscaller/callee patterns, time windows, geo tags, business labels
actionssend to extensions, queues, IVRs, outbound trunks, or prompts
fallbackbackup behavior when the primary action fails

2.2 Configuration workflow​

  1. Catalog entry points: map DID blocks, SIP URIs, and outbound destinations, aligning them with trunk direction and inbound_hosts settings.
  2. Author rules: edit via the console or config/routes/*.toml, referencing match.* helpers like from.*, to.*, request_uri.*, or any SIP header (regex supported).
  3. Bind actions: use action.dest for outbound trunks, action.queue/action.ivr for internal flows, or action.reject to return SIP 4xx/5xx.
  4. Layered policy: rely on priority plus source_trunks (or source_trunk_ids) to scope rules per ingress. List multiple trunks inside dest to express active/backup order.

Example:

[[routes]]
name = "vip-outbound"
direction = "outbound"
matchers = { callee_prefix = ["0086", "+86"], extension_group = "vip" }
actions = [
  { type = "send_trunk", trunk_id = "carrier-a", timeout = 30 },
  { type = "send_trunk", trunk_id = "carrier-b", timeout = 30 }
]
fallback = { type = "play_prompt", prompt = "vip_no_route.wav" }

2.3 Releasing changes​

  1. Always trigger Reload after saving drafts so the runtime picks up the latest routing file set.
  2. Use Diagnostics → Routing → Evaluate for both runtime and database datasets to ensure new rules resolve as expected before you publish.
  3. Run real calls through examples/voice_demo.rs or the built-in Web Dialer and compare resulting CDR entries with the intended billing template.

3. Billing templates​

Billing logic lives in models/bill_template.rs and is fully manageable via the console UI.

3.1 Design checklist​

  • Rate matrix: per-second or per-step billing, staged rates, minimum charges, and peak/off-peak deltas.
  • Currency & tax: customizable currency, tax rate, and rounding to integrate with finance systems.
  • Attach points: reference templates from routing, queue, or extension modules for policy+billing cohesion.

3.2 Example​

[bill_template.vip]
currency = "CNY"
billing_step = 6
free_seconds = 60
rates = [
  { prefix = "0086", price = 0.05 },
  { prefix = "001", price = 0.15 }
]

3.3 Validation & reconciliation​

  1. Export CDRs via Call Records and compare against template rates.
  2. Diagnostics → Billing highlights missing templates or failed matches.
  3. Extend revenue sharing via the addons/wholesale plugin when bespoke splits are required.

4. Best practices​

  • Active-active carriers: register per-carrier trunks and define priority plus failover steps to keep completion rates high.
  • Differentiated billing: bind distinct templates to rules based on business tags to offer VIP vs. regular pricing tiers.
  • Canary changes: stage routes with enabled = false, reload, then toggle from the console for controlled rollouts.
  • Compliance trail: manage trunk/routing/billing edits through PR review so Git history captures every change.

(Add a “Trunk + Routing flow” diagram and a “Billing template” screenshot here.)