<?xml version="1.0" encoding="utf-8"?>
<!--
  numbers.online — mod_cidlookup configuration for FreeSWITCH / FusionPBX

  Drop this file at:  conf/autoload_configs/cidlookup.conf.xml
  Then either reload the module:  fs_cli -x 'reload mod_cidlookup'
  or restart FreeSWITCH.

  What it does
  ============
  mod_cidlookup substitutes the inbound caller's number into the URL below and
  treats the HTTP response BODY, verbatim, as the caller-ID name. We point it at
  our plain-text CID endpoint, which always returns text/plain — a name, an
  operator-chosen spam tag prefix, or the literal "UNAVAILABLE".

  Why /v1/cid and not /v1/lookup
  ==============================
  mod_cidlookup cannot send HTTP request headers, so it cannot use Bearer/X-API-Key
  auth — the key travels as the ?key= query param, which only the /v1/cid endpoint
  accepts. /v1/cid also returns plain text; /v1/lookup returns JSON, and a PBX would
  render a raw JSON blob (or an error body) as the caller name. Never point this URL
  at /v1/lookup. If you want the full JSON response (carrier, line_type, spam_score)
  and header-based auth, use the Lua path instead — see numbers_online_cnam.lua and
  the full guide at https://numbers.online/integrations.

  The data returned is a supplementary signal. numbers.online does not assert that a
  caller is lawful, unlawful, or spam — your dialplan keeps every routing decision.

  Before you go live
  ==================
  1. Replace YOUR_API_KEY below with a key from https://numbers.online/docs
     (or POST https://numbers.online/v1/account/signup). Use a DEDICATED key for
     this endpoint and rotate it periodically — see the security notes in the guide.
  2. Adjust country=US if your bare national numbers are not US/NANP. This only
     affects how numbers WITHOUT a country code are interpreted.
  3. Optional spam tagging is opt-in. Append, inside the url value, e.g.
     &amp;spam_tag=Spam%3F&amp;spam_threshold=80
     With a tag set, a name scoring at/above the threshold is returned prefixed
     ("Spam? ACME CORP"); if there is no name, the tag alone is returned. Leave the
     spam_tag off entirely to never surface risk wording in the caller name.

  XML note: '&' MUST be written '&amp;' inside the url value below.
-->
<configuration name="cidlookup.conf" description="Caller ID name lookup via numbers.online">
  <settings>
    <!--
      Plain-text CID endpoint. ${caller_id_number} is the ONLY substitution token
      mod_cidlookup offers; it is the raw inbound number (often 10/11-digit
      national, not E.164). /v1/cid accepts +E.164, country-coded digits, or bare
      national digits resolved via &amp;country.
    -->
    <param name="url" value="https://numbers.online/v1/cid/${caller_id_number}?key=YOUR_API_KEY&amp;country=US"/>

    <!--
      Cache results in the local FreeSWITCH DB (core db / ODBC). 300s keeps repeat
      callers fast and trims per-lookup cost. Tune to taste; our data updates slowly.
    -->
    <param name="cache" value="true"/>
    <param name="cache-expire" value="300"/>

    <!--
      FAIL-OPEN timeouts. Caller-ID name lookup sits on the call-setup path, so it
      must never stall a call. 2000ms (2s) hard cap; on any timeout or error
      mod_cidlookup yields no name and the call proceeds unchanged.
    -->
    <param name="curl-timeout" value="2000"/>
    <param name="curl-warning-duration" value="1500"/>

    <!--
      KNOWN mod_cidlookup LIMITATION: the module sets CURLOPT_SSL_VERIFYPEER=0, i.e.
      it does NOT verify our TLS certificate. The request still goes over HTTPS, but
      the connection is not authenticated against a CA. Because of this (and because
      the API key rides in the query string, which can land in proxy/access logs),
      treat the key used here as low-trust: dedicate one key to this endpoint and
      rotate it on a schedule. Header-based auth with verified TLS is available via
      the Lua path.
    -->

    <!--
      Optional: have FreeSWITCH skip the lookup for numbers it can already name
      (e.g. resolved from a local directory). Leave commented unless you have one.
      <param name="skip-lookup-if-no-cid" value="true"/>
    -->
  </settings>
</configuration>
