Custom SIP Headers¶

This article describes the supported ways to add custom SIP headers when using libSoftphone SDK for Android and iOS.

Use custom SIP headers only for non-standard headers. Header names should start with X-.

Available Options¶

libSoftphone supports three practical approaches:

Static SIP account XML headers
Runtime account-level headers
Per-call headers

The right option depends on whether the value is static, whether the header needs SIP method or response-code filtering, and whether the value must be unique for a specific call.

Option	Scope	Dynamic	Method filtering	Response-code filtering	Best for
Account XML `<headers>`	Account	No	Yes	Yes	Fixed provisioning-time headers
`includeNonStandardSipHeader`	Account	Yes	Yes	Yes	Temporary metadata for upcoming SIP messages
`CallEvent` custom headers	Call	Yes	No	No	Unique metadata for a specific call

Static SIP Account XML Headers¶

Configure account XML headers when the header value is known during provisioning and should be part of the account configuration.

<headers>
    <header method="INVITE" name="X-CustomHeader" value="value"/>
    <header method="INVITE" responseCode="2xx" name="X-ResponseHeader" value="answered"/>
    <header method="*" name="X-OtherHeader" value="12345"/>
</headers>

Use method="*" to add a header to all SIP methods. Use responseCode to add a header to responses to the specified method. Omit responseCode to add a header to requests. This option is account-level and is saved with the SIP account.

For the full account XML reference, see Account XML.

Runtime Account-Level Headers¶

Use includeNonStandardSipHeader when the app needs to add or change a header at runtime. Use excludeNonStandardSipHeader to remove it again.

This mechanism is account-level state. The header is added only to SIP messages created after includeNonStandardSipHeader is called. Calling the method does not send a SIP message by itself.

Parameters¶

method: SIP method to include the header in, such as INVITE, INFO, UPDATE, REGISTER, or *.
responseCode: Use an empty string for request headers. For response headers, use a three-character pattern where x is a wildcard digit: xxx for all responses, 2xx for 200-299, 18x for 180-189, or an exact code such as 200.
name: SIP header name. It should start with X-.
value: SIP header value.

iOS¶

Use the registration object from SoftphoneBridge.

let registration = SoftphoneBridge.instance()?.registration()

registration?.includeNonStandardSipHeader(
    method: "INVITE",
    responseCode: "",
    name: "X-UserPreference",
    value: selectedPreference
)

// Trigger an action that creates a SIP message, for example hold or unhold.
SoftphoneBridge.instance()?.calls()?.setHeld(call, held: true)

// Clear the header if it should not apply to later SIP messages.
registration?.excludeNonStandardSipHeader(
    method: "INVITE",
    responseCode: "",
    name: "X-UserPreference"
)

The iOS SDK exposes these variants:

includeNonStandardSipHeader(method:responseCode:name:value:)
excludeNonStandardSipHeader(method:responseCode:name:)

includeNonStandardSipHeader(accountId:method:responseCode:name:value:)
excludeNonStandardSipHeader(accountId:method:responseCode:name:)

includeNonStandardSipHeader(index:method:responseCode:name:value:)
excludeNonStandardSipHeader(index:method:responseCode:name:)

Android¶

Use Instance.Registration.

Instance.Registration.includeNonStandardSipHeader(
    accountId,
    "INVITE",
    "",
    "X-UserPreference",
    selectedPreference
);

// Trigger an action that creates a SIP message.
Instance.Calls.setHeld(call, true);

// Clear the header if it should not apply to later SIP messages.
Instance.Registration.excludeNonStandardSipHeader(
    accountId,
    "INVITE",
    "",
    "X-UserPreference"
);

The Android SDK exposes these variants:

Instance.Registration.includeNonStandardSipHeader(
    String accountId,
    String method,
    String responseCode,
    String name,
    String value
);

Instance.Registration.includeNonStandardSipHeader(
    int index,
    String method,
    String responseCode,
    String name,
    String value
);

Instance.Registration.excludeNonStandardSipHeader(
    String accountId,
    String method,
    String responseCode,
    String name
);

Instance.Registration.excludeNonStandardSipHeader(
    int index,
    String method,
    String responseCode,
    String name
);

Runtime Header Limitations¶

The header is account-level state, not call-level state.
The header applies only to SIP messages created after it is included.
Setting a header does not send a SIP message by itself.
Clear temporary headers with excludeNonStandardSipHeader.
If multiple calls on the same account can create the same SIP method concurrently, the header can apply to the other call.

Per-Call Headers¶

Use per-call headers when a value must be unique to one outgoing call, such as a trace identifier.

Per-call headers are stored on the call event and are passed into SIP call creation. They do not support filtering by SIP method or response code. Use string values for per-call custom headers.

iOS¶

The iOS SDK exposes helper methods on SoftphoneCallEvent.

let call = SoftphoneCallEvent.create(withAccountId: "sip", uri: number)
let traceId = UUID().uuidString

call?.setCustomHeader(name: "X-TraceID", value: traceId)

let result = SoftphoneBridge.instance()?.events()?.post(call)

To set several headers at once, use mergeHeaders. It takes a JsonDict and adds each entry, overwriting any header already set under the same name.

let headers = JsonDict()
headers.set(traceId, forKey: "X-TraceID")
headers.set("mobile", forKey: "X-Source")

call?.mergeHeaders(headers)

To read per-call custom header values, use findCustomHeader(name:) for one value or the customHeaders property for the current dictionary.

let traceId = call?.findCustomHeader(name: "X-TraceID")
let allHeaders = call?.customHeaders

Android¶

The Android SDK uses the CallEvent transient dictionary. Put a Json.Dict under the customHeaders key before posting the call.

import java.util.UUID;
import cz.acrobits.ali.Json;
import cz.acrobits.libsoftphone.Instance;
import cz.acrobits.libsoftphone.event.CallEvent;

CallEvent call = new CallEvent(accountId, uri);

Json.Dict customHeaders = new Json.Dict();
customHeaders.put("X-TraceID", UUID.randomUUID().toString());

call.transients.put("customHeaders", customHeaders);

int result = Instance.Events.post(call);

Per-Call Header Limitations¶

Per-call headers are tied to a call event, not to all future SIP messages on the account.
They do not support SIP method filtering.
They do not support response-code filtering.
They are most useful before posting the outgoing call event.

Reading Received SIP Headers¶

Use findSipHeader to inspect the SIP headers received from the remote party in the call-establishing dialog. Do not confuse it with findCustomHeader, which reads back the outgoing headers you set on a CallEvent: findSipHeader reads what was received, findCustomHeader reads what you are sending.