Format phone numbers and SIP URIs for IllyVoIP SDK calls

For ordinary external calls through the IllyVoIP SDK, supply a reviewed international number. For an explicit SIP URI, apply your application’s destination policy before passing it to the SDK. The SDK constructs targets; it is not a complete number validator or an authorization service.

This guide targets the official Webphone SDK 1.4.2 browser distribution. Start with the installation guide, one managed phone owner and an authenticated backend that authorizes the user’s SIP identity. Keep permanent API keys and SIP passwords out of browser code.

1. Prefer one canonical number format

Use a complete number with country code from an authorized record. A simple application policy can require a leading plus and 7–15 digits. This is a syntax check for your workflow, not proof that the number exists, is callable or belongs to the named contact.

export function canonicalCallNumber(value) {
  const number = String(value ?? '').trim();
  if (!/^\+[1-9][0-9]{6,14}$/.test(number)) {
    throw new Error('Use a complete international number');
  }
  return number;
}

Resolve national numbers using a known country context before this step, or ask the user to correct them. Do not blindly strip every non-digit character from arbitrary text: an extension, pasted note or second number can otherwise become a different destination.

2. Understand what the SDK adds

In the reviewed runtime, the SDK trims surrounding whitespace. An explicit sip: or sips: target passes through. For a phone-like value and a bootstrap SIP domain, it constructs a SIP address with that domain and user=phone. It removes whitespace in that branch but does not remove every punctuation mark.

// Illustrations using a fictional bootstrap domain example.invalid:
// +12025550123      -> sip:+12025550123@example.invalid;user=phone
// +1 202 555 0123   -> sip:+12025550123@example.invalid;user=phone
// +1-202-555-0123   -> sip:+1-202-555-0123@example.invalid;user=phone
// sip:desk@example.invalid -> passed through as supplied

The hyphen example is why your application should normalize and validate before calling. Use getBootstrap for the actual supplied SIP domain; do not hard-code a proxy hostname copied from a screenshot. If no domain is available, stop your calling workflow and investigate initialization rather than guessing one.

3. Allow explicit SIP URIs only deliberately

A SIP URI contains a scheme, user/host information and possibly parameters. A displayed name is not the destination. URI syntax and routing permission are different questions. Passing an arbitrary remote host through the SDK does not establish IllyVoIP support or authorization to call it.

1. Decide whether your application needs explicit SIP URI entry at all. A numeric-only CRM action can reject it.
2. If needed, use a reviewed SIP parser and an explicit allowlist of permitted domains and identities.
3. Reject malformed input, control characters and unapproved parameters. Keep the parsed target separate from the display label.
4. Show the actual approved destination before a paid call or transfer.

Do not try to validate the full SIP grammar with the simple phone-number expression above. Likewise, choosing sips: does not by itself certify end-to-end media encryption or every hop’s transport behavior.

4. Use the validated value in the correct operation

Pass the approved target to phone.call for a new call, or the documented transfer action for the selected existing call. Keep transfer confirmation and its result handling separate from creating a new outgoing call. Prevent duplicate clicks and preserve uncertain outcomes instead of silently trying another target format.

5. Test without dialing first

1. Test clean international numbers, surrounding spaces, embedded punctuation, empty text and multiple pasted numbers locally.
2. Test explicit URI acceptance and rejection against the intended allowlist.
3. Check a missing bootstrap domain and stale customer-record selection.
4. Only after these checks, use an authorized destination for a short live call and confirm the resulting identity and audio.

For Support, retain the original input privately, your normalized value, SDK version and sanitized failure. Do not expose the complete bootstrap or call arbitrary sample numbers from this article.

Related guides

• Add browser calling with the Webphone SDK
• Transfer a call from an application using the Webphone SDK
• Format and validate recipient phone numbers before sending IllyVoIP SMS

Reference

Current instructions and technical reference: RFC 3261: SIP.

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.