SIP header context rules

AccessReadVIEWER+EditMEMBER+VIEWERs can open the Flow Designer read-only; saving rules requires MEMBER or above.

Voice sessions arrive with SIP metadata (headers on the INVITE). SIP header context rules turn that metadata into a flat list of keys and values the platform can attach to a managed LLM conversation as structured context — for example so the model or downstream tooling knows routing identifiers, environment labels, or caller-derived fields.

⚑Feature required: additionalProviders

The managed LLM integration (for example TOBi in the extended provider catalogue) and Channel Data Forwarding are only available when your platform enables non-default AI providers.

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

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

Screenshotguide.users.flow-designer.channel-data-forwardingneeds_review

Channel Data Forwarding section in the managed LLM panel with Manage and rule presets

Highlight: Channel Data Forwarding accordion, Manage, preset buttons

Reason: TelWeb v0.9.14 i18n and UI refactors changed labels/layout; screenshot needs visual review.

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.

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.

See also

• Source view — edit channelDataRules in the full flow definition.
• Nodes → Managed LLM — where the node appears on the canvas.
• Providers — managed LLM as a provider concept.
• Webhooks — async callback transport; forwarding rules address inbound SIP metadata, not the callback wire format.