Version: 0.9.14

SIP header context rules

Voice sessions arrive with SIP metadata (headers on the INVITE), and managed LLM sessions can also produce structured channel data during the call. Channel Data Forwarding rules turn that metadata into a flat list of keys and values the platform can attach to a managed LLM conversation, use in tool context, or forward back toward SIP during managed actions such as transfer.

Per-conversation callback security for async integrations is handled by the platform; you do not model the security token inside these rules.

Where to configure

Open the Flow Designer for your app.
Select the managed LLM node (or the flow settings entry that opens the managed LLM panel, depending on your layout).
Under Channel Data Forwarding, choose Manage to add presets or edit rules.
For bulk or advanced edits, use Source view on the flow definition JSON (see below).

JSON location

Rules are stored on the inline LLM configuration as channelDataRules: an array of rule objects next to fields such as bot or endpoint identifiers. Depending on your flow, that LLM block lives on the flow default provider or on a per-node provider override — wherever the managed LLM type is configured.

Minimal shape:

{
  "llm": {
    "type": "managed_llm",
    "botName": "example-bot",
    "channelDataRules": [
      {
        "action": "forward",
        "label": "Forward Environment header",
        "match": {"type": "equals", "value": "Environment"},
        "output": {
          "addToContextVariables": true,
          "sensitiveData": false,
          "encode": "none"
        }
      }
    ]
  }
}

Omit channelDataRules or set it to null when you do not need SIP-derived context.

Direction: inbound and outbound

Most rules start with the inbound direction: they read SIP INVITE headers and pass selected values into managed LLM context. Use this for routing identifiers, caller metadata, environment labels, or carrier-specific fields that the bot needs while deciding what to say or which managed action to trigger.

In v0.9.13, the same rule model also supports outbound Channel Data Forwarding. Outbound rules take values available to the managed LLM session — for example bot channel data, call variables, or previously forwarded context — and prepare them for SIP-facing actions such as transfer. Use outbound rules when the target SIP system expects specific headers or encoded routing values during a transfer or reinvite.

Keep responsibilities separate

Channel Data Forwarding is flow-scoped and belongs to managed LLM behavior. Platform and team header manipulation still handles general SIP header rewrite policy at the trunk or team edge.

Rule actions

Rules run in order. Each rule contributes zero or more entries (each has a string key, string value, and optional output flags). Disabled rules are skipped.

`forward` — copy or rename matching headers

For every SIP header whose name matches match, emit one or more entries.

match (required):

`match.type`	`match.value` meaning	Optional extras
`equals`	Header name must match exactly	`caseSensitive` (default false on names)
`startsWith`	Header name must start with the given prefix	`caseSensitive`
`regex`	Header name must match the JavaScript regex	`flags` (e.g. `i`)

Optional fields:

outputKey — Fixed output key; if omitted, the original header name is kept.
outputKeyTemplate — Build the key from a template (see Template syntax). Useful with regex captures.
valueTemplate — Build the value from a template; if omitted, the header value is used as-is (after multi-value handling).
multiValue — When the SIP stack exposes multiple values for one name: all (default), first, or join (use joinWith for the separator between values).

Example — forward one header by exact name

{
  "action": "forward",
  "label": "Environment label",
  "match": {"type": "equals", "value": "Environment"},
  "output": {"addToContextVariables": true, "sensitiveData": false}
}

Example — forward every X-Example-* header, keeping names

{
  "action": "forward",
  "label": "Custom X- headers",
  "match": {"type": "startsWith", "value": "X-Example-"},
  "outputKeyTemplate": "{{key}}",
  "output": {"addToContextVariables": true}
}

Example — regex capture into a shorter key

{
  "action": "forward",
  "label": "Strip prefix from header name",
  "match": {"type": "regex", "value": "^X-Example-(.+)$"},
  "outputKeyTemplate": "{{match.1}}",
  "output": {"addToContextVariables": true}
}

`splitKeyValueList` — parse a delimited list in one header

Reads a single header (sourceKey), splits it into pairs separated by pairDelimiter (default ~), each pair split into key and value by keyValueDelimiter (default =). Each pair becomes one entry; the output key is outputKeyPrefix + the parsed key.

Optional:

includeKeys — If set, only these parsed keys (case-insensitive) are emitted.
excludeKeys — Parsed keys to skip (case-insensitive).

Example

Header x-User-To-User with value ANI_TRANS=6952371127~CONNID=c5de0a3a-24d8-47c1-bb5a-13a62eef7f15:

{
  "action": "splitKeyValueList",
  "label": "Split routing block",
  "sourceKey": "x-User-To-User",
  "pairDelimiter": "~",
  "keyValueDelimiter": "=",
  "outputKeyPrefix": "channel_",
  "output": {"addToContextVariables": true}
}

This yields keys such as channel_ANI_TRANS, channel_CONNID, with the corresponding values.

`add` — emit one entry from templates

Adds a single entry with a fixed key and a value string built only from templates (no implicit “current header” unless you reference it).

Example

{
  "action": "add",
  "label": "Caller from From header",
  "key": "caller",
  "value": "{{header.From}}",
  "output": {"addToContextVariables": true, "encode": "none"}
}

Template syntax

Templates appear in outputKeyTemplate, valueTemplate, and the add action’s value. Placeholders use double curly braces: {{ ... }} (optional spaces inside are allowed).

Token	Resolves to
`{{key}}`	SIP header name for the row being processed (`forward` only).
`{{value}}`	SIP header value for that row (`forward` only).
`{{match.1}}`, `{{match.2}}`, …	Regex capture groups when `match.type` is `regex`.
`{{match.myName}}`	Named capture group `myName` when the regex defines it.
`{{header.Some-Name}}`	Value of header `Some-Name`; lookup is case-insensitive. If the header has multiple values, they are joined with a comma for the substitution.

Unknown placeholders resolve to an empty string.

Output options

Each rule may include an output object:

Field	Values / type	Role
`encode`	`none`, `uriComponent`, `base64`, `json`	Transform the value before it is stored (e.g. base64 for opaque blobs, `json` for JSON-encoded scalars or structures).
`addToContextVariables`	boolean (default true in the UI presets)	When true, entries are suitable for LLM / tool context in addition to structured channel payloads.
`sensitiveData`	boolean	Marks content that should be treated as sensitive in downstream handling.
`addToApiInvokation`	string or null	Optional filter for which API invocations receive the entry; the product UI may use a wildcard such as ``. Spelling* in saved JSON is `addToApiInvokation` (matches the platform schema).

Source view and advanced fields

The Source view / Edit toggle in the dialog edits the whole channelDataRules array as JSON. Use it when you need fields the accordion UI does not expose yet, for example:

enabled: false to keep a rule in the list but skip it
id for stable identification in diffs or tooling
Regex match.flags, match.caseSensitive, multiValue, joinWith
valueTemplate on forward rules
includeKeys / excludeKeys on splitKeyValueList

After editing, Apply Rules JSON in the dialog (or save the flow in Source view) runs the same validation as the rest of the Flow Designer; invalid rules block save.

Schema reuse elsewhere

The same rule structure is validated for some gateway settings (for example transfer-related header rules) in the platform schema. TelWeb may not expose every location yet; treat the JSON schema as the contract when editing source.

Where to configure​

JSON location​

Direction: inbound and outbound​

Rule actions​

forward — copy or rename matching headers​

splitKeyValueList — parse a delimited list in one header​

add — emit one entry from templates​

Template syntax​

Output options​

Source view and advanced fields​

See also​