Skip to content

Core Concepts

Jump to bottom
Andrey Egorov edited this page May 18, 2026 · 4 revisions

The Two Nodes

SIP PBX Trigger

This node opens a long-lived runtime trigger stream and emits workflow items when the daemon receives events.

Available trigger modes:

  • Trunk Event
  • Extension Event
  • Queue Event
  • AI Tool Call

SIP PBX

This node performs actions against the daemon runtime.

Available action groups:

  • Call
  • Dial
  • Media
  • Queue
  • Global recording
  • AI
  • Respond

Stable Public Identifiers

The package is intentionally built around a small set of IDs.

legId

Represents a live call leg.

Used for:

  • answering
  • hanging up
  • bridging
  • unbridging
  • media playback
  • recording
  • sending DTMF
  • queue placement

dialId

Represents an outbound dial session.

Used for:

  • waiting for dial progress
  • breaking a dial
  • coordinating sequential or parallel attempts

mediaId

Represents a playback or recording job running in the daemon.

Used for:

  • stopping media explicitly
  • waiting for background media to finish

Request IDs

These IDs exist for request-response flows:

  • authRequestId
  • recordRequestId
  • aiToolRequestId

They are produced by trigger branches and later consumed by response actions such as:

  • Respond to recording
  • Respond To Auth
  • Respond To AI Tool

ref

ref is the stable public name of a trigger group.

Examples:

  • trunk_main
  • extensions_sales
  • queue_support

Treat ref as part of your public workflow contract. Do not rename it casually after other nodes depend on it.

json.sipPbx Metadata

Most trigger items and many action results include a json.sipPbx object.

Typical fields:

  • legId
  • dialId
  • mediaId
  • authRequestId
  • recordRequestId
  • aiToolRequestId
  • ref

Use this metadata as a reliable handoff channel between nodes.

ID Resolution Rules

Many actions can work without hardcoding IDs because they resolve values from the current item.

legId resolution

Most call and media actions resolve legId in this order:

  1. Explicit value in the action Options
  2. item.json.legId
  3. item.json.sipPbx.legId

dialId resolution

Dial actions resolve dialId in this order:

  1. Explicit value in the action Options
  2. item.json.dialId
  3. item.json.sipPbx.dialId

mediaId resolution

Media control actions resolve mediaId in this order:

  1. Explicit value in the action Options
  2. item.json.mediaId
  3. item.json.sipPbx.mediaId

Request ID resolution

Response actions first try the hidden response handle attached by the trigger branch. If that handle is not present, they fall back to:

  1. Explicit Request ID in Options
  2. item.json.<requestId>
  3. item.json.sipPbx.<requestId>

Practical implication:

  • If you respond directly from the trigger branch, you usually do not need to map the request ID yourself.
  • If you store or forward items through other nodes, keep the json.sipPbx object intact.

Branches vs Single Results

Not every operation returns a single Result output.

Examples:

  • call.wait creates dynamic DTMF branches plus static branches such as Timeout and Ended
  • dial.wait always includes Answered, Interrupted, Timeout, and Failed, with optional Ringing, Progress, and Rejected
  • blocking media actions use Interrupted and Completed
  • queue triggers emit Placed, Dispatch, and Offline

Design workflows around branch semantics, not just the JSON payload.

Blocking vs Background Media

Play Audio, Play Tone, and Record Audio support two execution styles.

Blocking

The node waits until the media operation reaches a terminal event.

Use it for:

  • prompt-then-route IVR steps
  • short synchronous recordings
  • deterministic branch logic

Background

The node returns immediately with a mediaId, and the daemon keeps the media running.

Use it for:

  • hold music
  • long-running recordings
  • queue prompts
  • asynchronous orchestration with Stop Media or Wait Media

Global Recording Model

Global recording captures both sides of the live leg:

  • inbound remote audio
  • outbound PBX audio

Outbound PBX audio includes:

  • media playback generated by media operations
  • bridge audio sent toward the leg
  • the final mixed outbound signal after playback and bridge mixing

Trigger Lifetimes

Trigger streams are runtime-owned and stay alive while the workflow trigger is active.

Practical consequences:

  • Trigger behavior is not tied to a single webhook-like request.
  • If a trigger stream closes, the runtime removes it.
  • Your workflow must remain active for the trigger to keep receiving events.

Flow Scope and Ref Scope

Some behavior is intentionally workflow-scoped.

Extension dialing

Extension dialing does not ask for a trigger ref.

Instead, it searches matching registered endpoints across all extensions trigger refs in the current workflow scope.

This means:

  • it does not dial extensions from unrelated workflows
  • it can fan out across multiple extensions refs inside the same workflow

Queue operator lookup

Queue dispatch uses the queue trigger configuration and resolves matching operator extension numbers across same-flow extensions refs.

Duplicate refs

Advanced note:

  • active extensions trigger streams with the same public ref are rejected globally
  • trunk trigger streams can reuse the same public ref when internal flow-scoped refs differ

Best practice:

  • keep public refs unique unless you intentionally understand the scope rules

Overview

Trigger

Actions

Advanced

Clone this wiki locally