# Pingzo (Pingzoapp) — Comprehensive Technical Knowledge Base & AI Specification

> **Platform:** Pingzo (https://www.pingzoapp.com)  
> **Release:** Pingzo 2.0 (September 2026)  
> **Company:** Aurexis Technologies Pvt Ltd  
> **Description:** Enterprise-grade uptime monitoring, dedicated TCP/UDP port probing, Real User Monitoring (Core Web Vitals), 24h domain blacklist scanners, automated encrypted cloud archiving (Google Drive, Dropbox, AWS S3), and sub-15 second WhatsApp outage notifications.  
> **Machine-Readable AI Registry:** https://www.pingzoapp.com/ai/features (JSON schema of all capabilities, actions, parameters, and live pricing)

---

## 1. Plan Quotas & Pricing Matrix (Single Source of Truth)

| Metric / Feature | Free Tier | Starter Plan | Pro Plan (Most Popular) | Agency Plan |
| :--- | :--- | :--- | :--- | :--- |
| **Price (USD / mo)** | $0 / mo | **$5 / mo** | **$12 / mo** | **$29 / mo** |
| **Price (INR / mo)** | ₹0 / mo | **₹399 / mo** | **₹999 / mo** | **₹2,499 / mo** |
| **Standard Market Anchor** | $0 | ~~$15 / mo~~ (Save 67%) | ~~$35 / mo~~ (Save 66%) | ~~$89 / mo~~ (Save 67%) |
| **Monitor Quota** | 1 monitor | 15 monitors | 50 monitors | 100+ monitors |
| **Check Frequency** | 15 minutes | 1 minute | 30 seconds | 30 seconds |
| **Email Alerts** | Yes | Yes | Yes | Yes |
| **WhatsApp Alerts** | No | Yes (< 15s delivery) | Yes (< 15s delivery) | Yes (< 15s delivery) |
| **Telegram Bot** | No | Yes | Yes | Yes |
| **Slack & Discord Apps** | No | Yes (1-Click OAuth) | Yes (1-Click OAuth) | Yes (1-Click OAuth) |
| **Microsoft Teams Webhook** | No | Yes | Yes | Yes |
| **Custom HTTP Webhooks** | No | No | Yes (JSON POST) | Yes (JSON POST) |
| **Tag-Based Alert Routing** | No | No | Yes | Yes |
| **Real User Monitoring (RUM)** | No | No | Yes (Core Web Vitals) | Yes (Core Web Vitals) |
| **Port Probing (TCP/UDP)** | No | No | Yes (Postgres, Redis, Custom) | Yes (All Ports & Sockets) |
| **Cloud Storage Auto-Sync** | No | No | Yes (Daily & Weekly) | Yes (Daily, Weekly, Monthly) |
| **Domain Blacklist Scanner** | No | No | Yes (24h Automated) | Yes (24h Automated) |
| **3rd-Party Dependencies** | No | No | Yes (Stripe, OpenAI, AWS) | Yes (All Vendors + Custom URLs) |
| **SSL & Domain Expiry Alerts** | No | Yes (30, 14, 7 days) | Yes (30, 14, 7, 1 day) | Yes (30, 14, 7, 1 day) |
| **Status Pages** | No | No | Custom Slug Domain | White-label & Custom Domain |
| **Team Members** | 1 | 1 | 3 members | 10+ members |
| **Data Retention** | 7 days | 30 days | 90 days | 365 days |

---

## 2. Core Feature Setup & Developer Guides

### 2.1 Website & REST/GraphQL API Monitoring
* **What it is:** Active HTTP/HTTPS probing from global edge nodes with triple-zone verification to eliminate false positives.
* **Configuration Parameters:**
  - `name`: Friendly monitor label (e.g., `Authentication API`).
  - `url`: Full target address (`https://api.mybrand.com/health`).
  - `interval`: Check frequency (15m on Free; 1m on Starter; 30s on Pro/Agency).
  - `expectedStatusCode`: Target HTTP status (default `200`; supports `301`, `302`, `204`).
  - `timeoutMs`: Request timeout threshold (default `10,000ms`).
  - `headers`: Custom request headers (JSON object for API authorization tokens).
  - `keywordMatch`: String to assert in HTML/JSON body.
  - `keywordMatchType`: `contains` (fails if missing) or `not_contains` (fails if present).
* **Triple-Zone Verification Policy:** When a check encounters a non-200 response or timeout, Pingzo automatically initiates 3 retry probes from independent geographical zones before marking the monitor DOWN and firing alerts.

### 2.2 Dedicated Port Probing (TCP & UDP)
* **What it is:** Probes backend database ports and network daemons that do not serve HTTP web pages.
* **Supported TCP Services:**
  - **PostgreSQL:** Port `5432`
  - **Redis:** Port `6379`
  - **MySQL / MariaDB:** Port `3306`
  - **SSH:** Port `22`
  - **SMTP Mail:** Port `587` / `25`
  - **Custom Ports:** `1` to `65535`
* **Protocol-Aware UDP Engine:** Standard connectionless UDP packets are unreliable; Pingzo sends protocol-specific datagrams:
  - **Port 53 (DNS):** Transmits standard DNS root query datagrams (`. IN NS`).
  - **Port 123 (NTP):** Transmits client-mode NTP version 3 packets (`\x1b`).

### 2.3 Real User Monitoring (RUM) & Google Core Web Vitals
* **What it is:** Lightweight (<2KB), privacy-first, cookieless telemetry script capturing real visitor performance metrics.
* **Core Web Vitals Tracked:**
  - **LCP (Largest Contentful Paint):** Perceived load speed (Target: < 2.5s).
  - **TTFB (Time to First Byte):** Server response latency (Target: < 800ms).
  - **CLS (Cumulative Layout Shift):** Visual stability (Target: < 0.1).
  - **INP (Interaction to Next Paint):** User interface responsiveness (Target: < 200ms).
* **Installation Snippet:**
  ```html
  <script
    src="https://www.pingzoapp.com/telemetry.js"
    data-site="YOUR_RUM_SITE_TOKEN"
    defer
  ></script>
  ```
* **Next.js App Router Integration (`app/layout.tsx`):**
  ```tsx
  import Script from 'next/script'

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html lang="en">
        <head>
          <Script
            src="https://www.pingzoapp.com/telemetry.js"
            data-site="YOUR_RUM_SITE_TOKEN"
            strategy="afterInteractive"
          />
        </head>
        <body>{children}</body>
      </html>
    )
  }
  ```
* **Mandatory 3-Way Domain Verification:**
  1. *Script Tag:* Embed `telemetry.js` on your verified domain homepage and click "Verify".
  2. *HTML Meta Tag:* Add `<meta name="pingzo-verification" content="YOUR_RUM_SITE_TOKEN" />` in `<head>`.
  3. *DNS TXT Record:* Add a TXT record with host `@` and value `pingzo-verify=YOUR_RUM_SITE_TOKEN`.

### 2.4 Encrypted Cloud Storage Auto-Sync & Archiving
* **What it is:** Nightly automated streaming of CSV telemetry performance datasets and SLA audit summaries directly to personal cloud storage.
* **Security & Cryptography:** Zero plaintext token storage. All OAuth tokens and IAM credentials are encrypted at the application layer with **AES-256-GCM** using unique 16-byte Initialization Vectors (IVs) and authentication tags before database persistence.
* **Google Drive Setup (2-Minute Guide):**
  1. Open [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/).
  2. Under **Drive API v3**, select `https://www.googleapis.com/auth/drive.file`.
  3. Click **Authorize APIs** and authenticate with your Google account.
  4. Click **Exchange authorization code for tokens**.
  5. Copy the `access_token` and paste it into Pingzo. Pingzo automatically creates the `Pingzo Backups` folder and isolates permissions.
* **Dropbox Setup:**
  1. Open [Dropbox App Console](https://www.dropbox.com/developers/apps).
  2. Create an App with **Scoped Access** and **App Folder** permissions.
  3. Enable `files.content.write` in the Permissions tab.
  4. Generate access token (`sl.u...`) and paste into Pingzo.
* **AWS S3 / Cloudflare R2 / MinIO IAM Policy:**
  ```json
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": ["s3:PutObject", "s3:GetObject"],
        "Resource": "arn:aws:s3:::your-bucket-name/*"
      }
    ]
  }
  ```
* **Exported Triple-File CSV Schema Breakdown:**
  - **File 1 (`pingzo_monitors_summary_YYYY-MM-DD.csv`):**
    - Columns: `Monitor ID`, `Name`, `Target / URL`, `Type`, `Port`, `Current Status`, `Check Interval (min)`, `Total Outages (All Time)`, `Total Downtime Duration`, `Calculated Uptime %`, `SSL Expiry Date`, `SSL Days Remaining`, `Blacklist Status`, `Keyword Rule`, `Created Date (UTC)`, `Created Time (UTC)`.
  - **File 2 (`pingzo_incident_audit_log_YYYY-MM-DD.csv`):**
    - Columns: `Incident ID`, `Monitor ID`, `Monitor Name`, `Target URL`, `Outage Start Date (UTC)`, `Outage Start Time (UTC)`, `Recovery Date (UTC)`, `Recovery Time (UTC)`, `Outage Duration`, `Duration (Seconds)`, `Incident Status`, `Error Cause / Diagnostic`, `Max Escalation Stage`, `Resolved By`.
  - **File 3 (`pingzo_rum_vitals_analytics_YYYY-MM-DD.csv`):**
    - Columns: `Site ID`, `Domain`, `Verification Status`, `Verification Method`, `Record Date (UTC)`, `Record Hour (UTC)`, `Pageview / Sample Count`, `LCP P75 (ms)`, `LCP Rating`, `TTFB P75 (ms)`, `TTFB Rating`, `CLS P75`, `CLS Rating`, `INP P75 (ms)`, `INP Rating`, `Average LCP (ms)`, `Average TTFB (ms)`, `Average CLS`, `Average INP (ms)`, `Top Devices`, `Top Browsers`, `Site Created Date (UTC)`, `Site Created Time (UTC)`.

### 2.5 Domain & IP Blacklist / RBL Scanner
* **What it is:** Daily 24-hour scans across major anti-spam DNSBL databases to protect transactional email deliverability and domain reputation.
* **Databases Checked:** Spamhaus DQS (`zen.spamhaus.org`), SpamCop (`bl.spamcop.net`), Barracuda RBL (`b.barracudacentral.org`), Google Safe Browsing.

### 2.6 3rd-Party Outage & Dependency Tracker
* **What it is:** Correlates your application downtime with upstream cloud outages.
* **Supported Cloud Services:** Stripe, OpenAI (ChatGPT & API), AWS, Cloudflare, Vercel, Supabase, Neon Postgres, MongoDB Atlas, Upstash (Redis & QStash), GitHub, Twilio SendGrid, Postmark, Resend.
* **Custom Status URLs:** Supports public Atlassian Statuspage, Instatus, RSS, or `/healthz` endpoints.

### 2.7 Alert Channels & Tag-Based Routing
* **Official WhatsApp Business API:** Sub-15 second outage notifications. Requires phone number with country code (e.g. `+919876543210`) verified via one-time SMS/WhatsApp OTP.
* **Telegram Bot:** Real-time messages via `@Pingzoappbot`. Send `/start` to retrieve Chat ID and link channel.
* **1-Click Slack & Discord Apps:** Seamless OAuth authentication to automatically manage channel incoming webhooks.
* **Microsoft Teams:** Webhook connector URL integration.
* **Custom HTTP Webhooks:** Sends structured JSON POST payloads to your endpoint:
  ```json
  {
    "event": "monitor.down",
    "timestamp": "2026-09-29T04:20:00Z",
    "monitor": {
      "id": "cmq_monitor_123",
      "name": "Production Database",
      "url": "db.internal.mybrand.com",
      "type": "port_tcp",
      "port": 5432,
      "tags": ["database", "prod"]
    },
    "incident": {
      "id": "inc_987654",
      "error": "TCP Socket Connection Timeout (10000ms)"
    }
  }
  ```
* **Tag-Based Routing:** Assign tags (`#database`, `#frontend`, `#payments`) to monitors and configure alert channels to filter notifications by tag to prevent alert fatigue.
* **On-Call Duty & Shift Scheduling:** Configure active shift days (e.g. Mon-Fri), working hours (e.g. 09:00 - 18:00), and timezones per channel. Assign recipient names (e.g. `Alex DevOps`) for personalized alerts. Live `🟢 On-Duty Now` vs `⚪ Off-Duty` indicators with automatic shift handoffs.
* **Multi-Stage Automated Escalation:**
  - **Stage 1 (Immediate)**: Dispatched immediately (< 15s) upon multi-region failure to on-duty team members (Starter, Pro, Agency).
  - **Stage 2 (Configurable Delay)**: Fires after customizable threshold (5m, 10m, 15m, 30m, 45m, 60m) to secondary leads if unresolved (Pro, Agency).
  - **Stage 3 (High-Priority Multi-Team)**: Fires after 15m–120m for prolonged outages to executive/emergency responders (Agency).
  - **Incident Resolver Tracking**: Complete audit trail under `/dashboard/incidents` showing responder names, escalation stage, and manual vs auto-recovery resolver identities.

### 2.8 Bulk CSV & JSON Monitor Import
* **Format Specification:**
  ```csv
  name,url,type,intervalMinutes,port
  Main Storefront,https://mybrand.com,http,5,
  Authentication API,https://api.mybrand.com/health,http,2,
  Postgres DB,db.internal.mybrand.com,port_tcp,2,5432
  Redis Cache,redis.internal.mybrand.com,port_tcp,5,6379
  ```

### 2.9 Node.js Heartbeat SDK (`@pingzoapp/sdk`)
* **Installation:** `npm install @pingzoapp/sdk`
* **Usage:**
  ```javascript
  const Pingzo = require('@pingzoapp/sdk');
  const pingzo = new Pingzo('your-heartbeat-secret-id');

  // Report task success
  await pingzo.ping();

  // Report immediate task failure
  await pingzo.ping('fail', 'Out of Memory Exception');
  ```

### 2.10 Public Probe Transparency, Host Opt-Out & Ownership Dispute Resolution
* **Transparency Portal:** `https://pingzoapp.com/probe`
* **Opt-Out Mechanism (`POST /api/probe/block`):**
  - External network administrators and hosting providers can request immediate probe cessation for their IP or domain name without creating an account.
  - Request Body: `{"target": "example.com", "reason": "admin_opt_out"}`
  - Automated Platform Impact:
    1. **Edge Probe Halt:** Pingzo immediately halts all synthetic HTTP, SSL, and TCP socket probes to that hostname or IP across the global edge network.
    2. **Monitor Auto-Pause:** Any active monitors matching the target domain or IP are automatically transitioned to a paused state with `isBlocked: true` and display the `🚫 Blocked (Opt-Out)` badge in the customer dashboard.
    3. **Non-Alarming Alert:** Pingzo dispatches a dedicated `PROBE_OPT_OUT` event notification across configured alert channels (WhatsApp, In-App, Email, Telegram, Slack, Discord, MS Teams), informing the user that monitoring was paused due to a host exclusion request rather than an infrastructure downtime outage.
* **Customer Ownership Verification & Dispute Protocol:**
  - If a legitimate domain or server owner's target is opted out, they can verify control in under 60 seconds from the dashboard:
  - **1. Challenge Generation (`GET /api/monitors/[id]/verify-ownership`):**
    - Returns `{ challengeToken: "pz_disp_<16-hex>", dnsTxtRecord: "pingzo-verify=pz_disp_...", httpUrl: "http://<target>/.well-known/pingzo-verify.txt", targetHost: "example.com" }`
  - **2. Method A — DNS TXT Record (Domains):**
    - Host / Name: `@` (or subdomain)
    - Value: `pingzo-verify=pz_disp_<token>`
    - Verification Trigger: `POST /api/monitors/[id]/verify-ownership` with body `{"method": "dns"}`
    - Engine performs authoritative `dns.resolveTxt` query. If valid, deletes the `BlockedTarget` record, clears `isBlocked`, and automatically resumes probe monitoring.
  - **3. Method B — HTTP `.well-known` File (Raw IPs & Web Servers):**
    - File Path: `http://<IP_OR_HOST>/.well-known/pingzo-verify.txt`
    - Content: `pz_disp_<token>` (HTTP 200 OK, `text/plain`)
    - Verification Trigger: `POST /api/monitors/[id]/verify-ownership` with body `{"method": "http"}`
    - Engine performs direct HTTP GET fetch, verifies token match, removes the block, and restores monitoring.
* **Administrative Override & Security Auditing:**
  - Platform administrators maintain manual override capabilities (`/api/admin/monitors/dispute`) to inspect dispute logs, cross-reference registrar WHOIS data, and enforce cryptographic ownership authenticity.

---

## 3. Troubleshooting & Common AI Resolution Playbooks

### Issue 1: Monitor shows DOWN, but site opens fine in user browser
* **Cause 1 (Cloudflare / WAF Blocking):** Cloudflare bot protection or AWS WAF may be challenging Pingzo's automated probe user agent (`PingzoBot/2.0`).
  * *Fix:* Whitelist Pingzo probe IP ranges or User-Agent header in Cloudflare WAF.
* **Cause 2 (SSL Handshake / Expired Intermediate Cert):** Server may be missing intermediate CA certificates (opens fine on desktop with cached chains, but fails headless SSL validation).
  * *Fix:* Reinstall fullchain.pem on web server.

### Issue 2: Google Drive Auto-Sync fails with 401 UNAUTHENTICATED
* **Cause:** Google OAuth access tokens expire after 60 minutes.
* **Resolution:** In Cloud Auto-Sync, click the Trash icon to disconnect, generate a fresh token from Google OAuth Playground with `drive.file` scope, and reconnect.

### Issue 3: WhatsApp alert not arriving
* **Cause 1:** Phone number missing country code (e.g. `9876543210` instead of `+919876543210`).
* **Cause 2:** Phone number not verified with OTP in dashboard.
* **Cause 3:** Monitor has tag routing enabled and does not match the channel's configured tag filter.

### Issue 4: RUM Telemetry script blocked by CSP
* **Cause:** Content Security Policy header missing `connect-src` permissions.
* **Fix:** In web application CSP headers, ensure `connect-src` includes `https://www.pingzoapp.com` and `https://pingzoapp.com`.

### Issue 5: Monitor shows "🚫 Blocked (Opt-Out)" status badge
* **Cause:** A system administrator or host provider submitted an opt-out exclusion for the monitored domain or IP address at `https://pingzoapp.com/probe`.
* **Resolution:**
  1. Click the **[🛡️ Verify Ownership]** button next to the blocked monitor in the Pingzo dashboard.
  2. For domain names, add a DNS `TXT` record with value `pingzo-verify=pz_disp_<token>` and click **Verify TXT Record**.
  3. For raw IP addresses, upload the token to `/.well-known/pingzo-verify.txt` and click **Verify File**.
  4. Upon successful verification, the exclusion is instantly cleared from `BlockedTarget` and synthetic monitoring resumes automatically.

---
© 2026 Aurexis Technologies Pvt Ltd. (https://www.pingzoapp.com)