The IllyVoIP Webphone SDK can attach custom SIP headers to registration, outgoing-call and incoming-answer requests. Use them for small application references, such as an opaque CRM contact ID or desk label, when your receiving system has a defined use for that metadata.
This is not the same as adding HTTP headers to the REST API. A custom SIP header does not grant permission, override caller-ID policy or guarantee that a downstream carrier, CRM or call-history record will retain it. Agree on the receiving system’s behavior before relying on the field.
1. Choose minimal metadata and a clear receiving contract
Prefer a non-sensitive internal reference over a person’s name, email, complete CRM record or authorization token. SIP requests may pass through multiple systems. Do not use this channel to send passwords, API keys, browser tokens, payment information or personal notes.
Define the field name, allowed values, intended recipient and retention policy. Use an application-specific X- header name rather than trying to replace protocol headers such as From, To, Contact, Route or Authorization. Leave the SDK’s managed browser-token header alone.
Custom metadata is useful only if the receiving integration explicitly reads and correlates it. It does not automatically populate an IllyVoIP contact field or create a HubSpot association.
2. Select the narrowest header scope
The SDK options include customHeaders for general use and registerHeaders, callHeaders and answerHeaders for their respective operations. Individual register, call and answer requests can also receive headers. Prefer the per-operation scope when a value applies to one call rather than every registration or call.
For example, a contact reference belongs to the selected call. A desk reference may belong to registration. Do not leave a previous contact’s reference in a global option when an agent moves to a different contact.
Keep each custom header name unique across the selected scopes. Do not rely on duplicate-header precedence as a way to override a value; explicitly build the intended header set.
3. Validate references before passing them to the SDK
function crmReferenceHeaders(reference) {
if (typeof reference !== 'string' ||
!/^[A-Za-z0-9_-]{1,64}$/.test(reference)) {
throw new Error('Invalid CRM reference');
}
return { 'X-CRM-Contact-Id': reference };
}This example is deliberately stricter than a general header-value grammar. It rejects line breaks, whitespace and arbitrary user content. The validation belongs at your application boundary; do not assume that converting an object into SIP headers provides authorization or sufficient security filtering.
Use your own opaque reference format if needed, but retain explicit length and character limits. Resolve the reference from the authenticated user’s authorized record, not from an unchecked URL parameter.
4. Attach the reference to the intended operation
// This places a real call when executed against a registered phone.
// approvedTarget and contactReference must already be authorized.
const headers = crmReferenceHeaders(contactReference);
const call = await phone.call(approvedTarget, { headers });The example assumes an already initialized, registered phone and a user-authorized outgoing call. It can create billable usage. Do not run it automatically on page load just to test header formatting.
For registration metadata, pass a headers object to phone.register(options), or configure registerHeaders during setup. For an incoming answer, use call.answer({headers}) on the selected incoming call. Do not repeat registration or answer an additional call merely to inspect a header.
5. Confirm what actually reaches the receiver
First test your value builder locally with valid references, an empty string, an oversized string and injected carriage-return/newline characters. Then, during an authorized integration test, inspect a sanitized request at the intended receiving boundary and confirm the correct record mapping.
A locally constructed header is not proof of downstream delivery. Intermediaries can remove or transform headers, and the receiving system may ignore unknown fields. If the reference is essential to business processing, define what happens when it is missing instead of guessing the contact from the caller’s number.
Do not export full SIP traces casually. They may contain telephone numbers, authentication material or network details. Keep only the fields needed to show whether your approved custom metadata was attached and received.
Troubleshooting
Wrong contact reference: check whether a stale value was stored globally. Duplicate values: inspect overlapping global and operation scopes. Receiver sees no header: verify its documented support and the signaling path. Call rejected: inspect the actual call error; a custom reference cannot bypass calling permissions or identity policy.
Related guides and reference
- Add browser calling with the Webphone SDK
- Use IllyVoIP calling inside your CRM
- Custom SIP header reference
Reviewed 10 October 2026 against the current IllyVoIP reference and implementation. SDK examples target version 1.4.2 where applicable. Local example checks do not certify a completed live call, routing change or third-party integration.