MicroSIP integration

Show a caller's name, line type, and a low-confidence risk signal as a Windows toast the moment an inbound call rings your MicroSIP softphone. MicroSIP runs a command on each incoming call; that command asks numbers.online about the caller and pops a desktop notification.

Positioning. This is a desktop-softphone demo of the numbers.online lookup API — a quick way to see the signal on your own screen. For production call flows the real integration point is your PBX/SBC (see asterisk-freepbx.md), where the lookup can label, route, or challenge a call before it reaches an extension. numbers.online returns supplementary identity and risk signals; the operator keeps every routing and blocking decision. The API never asserts that a call is lawful, unlawful, "safe", or "spam".

What you get

On each inbound call a toast appears with:

• the caller name (CNAM) when available, otherwise No name available;
• the caller's national number, line type, and country;
• a risk signal rendered as Risk signal: <n>/99 (low-confidence supplementary signal).

An optional operator-chosen label (default Possible nuisance call) is prefixed to the name only when the risk score meets a threshold you set. Risk wording is opt-in by design — clear $RiskTag in the script to never surface it.

Files

Both files are downloadable below — and from the integrations page:

Setup

1. Create an API key. Sign up once and copy the key it returns:

   curl -X POST https://numbers.online/v1/account/signup ^
     -H "Content-Type: application/json" ^
     -d "{\"email\":\"[email protected]\",\"name\":\"Your Company\"}"
   

   The free tier is unbilled at 60 requests/min. Full docs: https://numbers.online/docs.

2. Save both files to C:\tools\numbers-online\ so you have:

   C:\tools\numbers-online\NumbersOnlineLookup.ps1
   C:\tools\numbers-online\numbers-online-lookup.bat
   

3. Set the API key as a user environment variable named NUMBERS_ONLINE_API_KEY (the script reads it from there — it is never stored in the script):

   setx NUMBERS_ONLINE_API_KEY "YOUR_API_KEY"
   

   Open a new session afterwards so the variable is visible to MicroSIP.

4. Point MicroSIP at the wrapper. Close MicroSIP, edit microsip.ini, and set the incoming-call command under [Settings]. Quote the path (it contains no spaces here, but quoting is required if you relocate it under a path that does):

   [Settings]
   cmdIncomingCall="C:\tools\numbers-online\numbers-online-lookup.bat"
   

5. Restart MicroSIP. On the next inbound call you'll see the toast.

If your trunk delivers numbers for a country other than the US/Canada, open NumbersOnlineLookup.ps1 and adjust $DefaultCountryCode / $DefaultNationalLength near the top.

The raw-number caveat

MicroSIP passes the raw SIP From user-part with zero normalization as the single argument. In practice that is often a 10-digit national or 11-digit number, only rarely full +E.164, and can even be anonymous or an alphanumeric SIP username. The script defends against this:

• non-numeric callers (anonymous, alphanumeric users, empty) are ignored — no toast;
• a 10-digit number gets the default country code prepended;
• an 11-digit number already starting with the country code is treated as +-prefixed;
• a value with a leading + is trusted as already-international.

Because numbers arrive without a +, the script interprets bare national numbers using $DefaultCountryCode. A misconfigured default country code is the most likely cause of an odd result.

Fail-open

The integration never blocks or delays a call. MicroSIP launches the script as a fire-and-forget side effect and ignores its output entirely — the toast is the only visible product. On any guard miss, missing API key, timeout (5s), or HTTP error (401/402/429/offline), the script simply exits silently and the call proceeds as normal. No popup is not an error; it just means there was nothing to show.

Privacy

The script logs nothing. Raw caller numbers and your API key never touch disk or any debug output; the key is read only from the NUMBERS_ONLINE_API_KEY environment variable at runtime.

Pricing

Billing matches the rest of the lookup API: $0.004 per lookup that includes a fresh CNAM dip, $0.002 for a cache hit or when no name supplier is available, and invalid numbers are free. The free tier is unbilled at 60 requests/min.

For API keys or higher rate limits: [email protected].