Web Responder & Click-to-Call — Technical Reference

For day-to-day operations and the authoritative deploy process, see docs/webresponder-runbook.md. This doc is the technical reference for the two features and their NS integration.

What It Does

A Flask app serving two features, both driven by per-config entries in domains.json keyed by a free-form id (<ns-domain>-<suffix>):

1. SMS Responder — NS calls the /webresponder webhook (via a dial rule); the app texts the caller hours/directions and returns confirmation XML.
2. Click-to-Call — /widget.js serves an embeddable button; /click-to-call originates a queued callback via the NS legacy API.

A Zoho form per feature posts to /update-sms or /update-domain to upsert config. /update-sms also auto-provisions the NS routing objects.

Server

Files in This Repo

Routes

All app routes must be added to server-config/Caddyfile or they 404 (fall through to the static server).

domains.json Schema

{
  "pressone.net-sms": {
    "api_domain": "pressone.net",
    "user": "2000",
    "ns_system_user": "8001",
    "from_number": "19294873999",
    "message": "Our hours are Mon-Fri 9am-5pm. We are at 123 Main St, Tampa FL."
  },
  "pressone.net-sales": {
    "api_domain": "pressone.net",
    "queue": "9002@pressone.net",
    "branding": { "button_text": "Call Us Now", "button_color": "#1a73e8", "company_name": "PressONE", "logo_url": "" }
  }
}

No restart needed when domains.json changes — re-read on every request.

NS API Details

SMS Auto-Provisioning (/update-sms)

After saving config, provision_sms_responder() runs three idempotent (409 / "already exists" → success), best-effort steps and returns a per-step status ({"user":..,"dial_rule":..,"answer_rule":..}). Config is saved regardless; partial failures still return 200.

1. Create system user — POST .../v2/domains/{api_domain}/users — Simple User {ns_system_user}, service-code=system-webresponder, email-address=operations@pressone.net (hard-coded).
2. Create dial rule — POST .../v2/domains/{api_domain}/dialplans/{api_domain}/dialrules (note the separate {dialplan} segment — plan named after the domain), application To Web, matches webresponder{ns_system_user}, dial-rule-parameter=https://ns-scripts.pressone.net/webresponder?id={id}.
3. Set answer rule — PUT .../v2/domains/{api_domain}/users/{ns_system_user}/answerrules/* forward-always → webresponder{ns_system_user}; falls back to POST .../answerrules if the * timeframe doesn't exist yet.

Routing chain: call → {ns_system_user}@{api_domain} → answer rule forward-always → webresponder{ns_system_user} → dial rule (To Web) → webhook GET ?id={id} → SMS sent.

What NS Sends to the SMS Webhook

XML Responses

Success: <Response><Say>We've texted you our hours and directions…</Say><Hangup/></Response> Error: <Response><Say>Sorry, we could not send directions at this time.</Say><Hangup/></Response>

Environment Variables (.env on server, gitignored)

Caddy Config

server-config/Caddyfile (symlinked to /etc/caddy/Caddyfile). The ns-scripts.pressone.net block forwards app routes to :5100, everything else to the static container on :8081:

ns-scripts.pressone.net {
    handle /webresponder*   { reverse_proxy localhost:5100 }
    handle /widget.js*      { reverse_proxy localhost:5100 }
    handle /click-to-call*  { reverse_proxy localhost:5100 }
    handle /update-domain*  { reverse_proxy localhost:5100 }
    handle /update-sms*     { reverse_proxy localhost:5100 }
    handle                  { reverse_proxy localhost:8081 }
}

After editing: caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy.

Service Management

systemctl status ns-webresponder
systemctl restart ns-webresponder        # after app.py or .env changes
journalctl -u ns-webresponder -f
journalctl -u ns-webresponder -n 50 --no-pager

Running Tests Locally

cd /Users/shripald/ClaudProjects/Netsapiens-Scripts/webresponder
venv/bin/pytest -v

Deploying a Code Change

Git discipline — edit local → commit → push → pull on server → restart. Never hand-edit files on the server.

# On the Mac
cd ~/ClaudProjects/Netsapiens-Scripts
cd webresponder && venv/bin/pytest -q && cd ..
git add -A && git commit -m "feat(webresponder): describe change" && git push

# On the server
ssh root@ns-scripts.pressone.net
cd /opt/ns-scripts && git pull
systemctl restart ns-webresponder            # for app.py / .env changes
# caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy   # for Caddyfile changes
journalctl -u ns-webresponder -n 20 --no-pager

domains.json is gitignored, so pulls don't clobber live config.