Skip to main content

SipHeaderMapping

Persistent header mapping. Derived mappings may share a providerHeader with a plain mapping, require transform, and must target an X-* header outside the reserved X-SipSandwich-* namespace. At most one passthrough mapping is allowed, it uses providerHeader "*", and no other mapping may target a header inside its prefix.

providerHeaderstringrequired

Header name received from or written toward the SIP provider. Forward-all (passthrough) mappings use "*".

retellHeaderstringrequired

Retell-visible X-* or P-Asserted-Identity header. For passthrough mappings this is the dash-terminated X-* prefix, for example X-SIP-.

Possible values: Value must match regular expression ^(X-[A-Za-z0-9_-]+|P-Asserted-Identity)$

directionstringrequired

inbound copies the carrier value to Retell; bidirectional also rewrites it back on provider-bound transfers; derived computes a new X-* header from part of the carrier header using transform. passthrough forwards every eligible carrier header as prefix + header name on the SIP edge, with no lookup, plus From/To name, user, and host parts; credentials, routing, and body headers are never forwarded.

Possible values: [inbound, bidirectional, derived, passthrough]

transform object

Structured rule that derives a header value from one received carrier header. The result is sanitized to one line of at most 256 characters; an empty result omits the header.

sourcestring

Possible values: [display_name, uri_user, uri_host, full_value, header_parameter]

Default value: full_value
parameterstring

Header parameter name when source is header_parameter, for example tag.

Possible values: <= 40 characters

steps object[]

Possible values: <= 12

  • Array [
    • oneOf
    opstringrequired

    Possible values: [keep_before]

    delimiterstringrequired

    Literal, case-insensitive delimiter. When absent from the value, the whole value is kept.

    Possible values: non-empty and <= 20 characters

    occurrencestring

    Possible values: [first, last]

    Default value: first
  • ]
    • SipHeaderMapping
    {
      "providerHeader": "string",
      "retellHeader": "string",
      "direction": "inbound",
      "transform": {
        "source": "full_value",
        "parameter": "string",
        "steps": [
          {
            "op": "keep_before",
            "delimiter": "string",
            "occurrence": "first"
          },
          {
            "op": "keep_after",
            "delimiter": "string",
            "occurrence": "first"
          },
          {
            "op": "remove_words",
            "words": [
              "string"
            ]
          },
          {
            "op": "replace_text",
            "find": "string",
            "replaceWith": ""
          },
          {
            "op": "change_case",
            "mode": "lower"
          }
        ]
      }
    }