# Pingwire

> Pingwire is a developer-first messaging and notification platform. Developers send a message, alert, or reminder into a chat in under 30 seconds — from a server, website, CLI, cron job, or plugin — using one HTTP call or one CLI command. Messages reach humans in a real-time chat UI and on their phone via web push. It runs as a managed service at pingwire.dev and is also available to self-host.

Base URL: https://pingwire.dev
Auth: HTTP Bearer API key — `Authorization: Bearer pw_live_...` (create keys in Account → API keys). Scopes: send, schedule, read, admin.

## Send a message (the core endpoint)

POST https://pingwire.dev/api/v1/messages.php
Headers: Authorization: Bearer <api_key>; Content-Type: application/json
Body (JSON, form-encoded, or raw text/plain all accepted):
{
  "channel": "deploys",      // target channel slug (auto-created on first send) — OR:
  "to": "username",          // a username or conversation UUID for a direct message
  "text": "Build #123 passed",
  "title": "CI",             // optional bold headline
  "priority": "high",        // min | low | default | high | urgent
  "tags": "ci,rocket",       // optional comma-separated labels
  "url": "https://ci/123"    // optional click-through URL
}
Response: 201 { "id", "uuid", "conversation", "priority", "created_at" }

Alias: POST https://pingwire.dev/api/v1/notify.php (identical; raw text body becomes the message, with channel in the query string e.g. ?channel=alerts).

Self-notification: on a single account, messages you send via the API, CLI, webhooks, or the scheduler push to your own phone once notifications are enabled on a device — no second account needed. The only messages not pushed back to you are the ones you type yourself in the chat UI (no echo). A separate "bot"/sender account is optional, useful for teams, shared channels, or a dedicated send-only identity.

List messages: GET https://pingwire.dev/api/v1/messages.php?channel=deploys&limit=30

Example (curl):
curl -X POST https://pingwire.dev/api/v1/messages.php \
  -H "Authorization: Bearer pw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"channel":"deploys","text":"Build passed","priority":"high"}'

## Incoming webhooks (no auth header)

POST https://pingwire.dev/hook/{token}
The URL token is the secret. Accepts JSON, form data, or raw text (auto-detected).
Common fields mapped automatically: text | message | content | body, and title | subject.
Ideal for GitHub, CI, and uptime monitors. Create a webhook in Account → Webhooks.

## Reminders (scheduled & recurring)

POST https://pingwire.dev/api/v1/reminders.php  (scope: schedule)
One-off:    {"channel":"team","text":"Release","run_at":"2026-06-01T15:00:00Z"}
Recurring:  {"channel":"team","text":"Standup","cron":"0 9 * * 1-5","timezone":"America/New_York"}
GET  https://pingwire.dev/api/v1/reminders.php            list
DELETE https://pingwire.dev/api/v1/reminders.php?id=N     cancel

## Channels & identity

GET  https://pingwire.dev/api/v1/channels.php    list channels you can post to
POST https://pingwire.dev/api/v1/channels.php    {"name":"Deploys"} create a channel
GET  https://pingwire.dev/api/v1/me.php          identity for the current key (whoami)

## QR Channels (subscribe-by-scan)

QR Channels let anyone subscribe to your notifications by scanning a branded QR code — no account or app required. Send one message and it pushes to every device that scanned. Overview: https://pingwire.dev/features/qr-channels

Create a QR channel (REST): POST https://pingwire.dev/api/v1/channels.php with {"qr":true,"name":"Deploys","description":"...","brand_color":"#0F62FE"} → returns subscribe_url + qr_png_url + qr_svg_url.
Public subscribe flow: scanning the QR opens https://pingwire.dev/s/{token} (a no-account web-push opt-in page); QR images are at https://pingwire.dev/qr/{token}.png and .svg; one-click unsubscribe at https://pingwire.dev/u/{unsub_token}.
Public subscribe API (no auth, rate-limited): POST https://pingwire.dev/api/v1/public/subscribe.php {"subscribe_token":"...","webpush":{"endpoint":"...","keys":{"p256dh":"...","auth":"..."}}} → returns an unsub_token.
Send to all subscribers: POST https://pingwire.dev/api/v1/messages.php {"channel":"deploys","text":"...","title":"...","priority":"high"} — fans out as web push to every active subscriber; expired endpoints (404/410) auto-deactivate.
List + subscribers + QR asset: GET /api/v1/channels.php (QR channels include subscribe_url and counts), GET /api/v1/channels/{id}/subscribers, GET /api/v1/channels/{id}/qr.(png|svg).
CLI: pingwire qr create --name "Deploys" | pingwire qr list | pingwire qr image <id> --format png --out file | pingwire qr subscribers <id> | pingwire qr send <slug> --title "..." --body "..."
MCP tools (docs: https://pingwire.dev/docs/mcp.php): create_qr_channel(name, description?, brand_color?), list_qr_channels(), get_subscribe_qr(channel), send_to_channel(channel, body, title?, priority?).
Plans: FREE = 1 channel, 50 subscribers/channel, no custom branding, 30-day analytics, "Powered by Pingwire" footer. PRO = unlimited channels & subscribers, custom logo/color/QR style, vanity slug, 365-day analytics, no footer.

## CLI

Install: ln -s /home/pingwire.dev/public_html/cli/pingwire /usr/local/bin/pingwire
Config:  PINGWIRE_API_KEY and PINGWIRE_URL (env or ~/.pingwirerc)
Commands:
  pingwire send [--channel X | --to USER] [--title T] [--priority P] [--url U] "message"
  pingwire send --channel deploys < build.log          # read body from stdin
  pingwire remind "+10 minutes" "stand up" --channel team
  pingwire remind --cron "0 9 * * 1-5" --channel team "Standup"
  pingwire channels
  pingwire whoami

## Limits & errors

Rate limits: sends 120/min/key, webhooks 60/min/token, reminders 60/min/key. Over limit → HTTP 429 with Retry-After.
Errors are JSON: { "error": "<code>", ... } with the matching HTTP status (401 invalid_api_key, 402 payment_required — the account needs Supporter Access (a monthly subscription managed at pingwire.dev/account.php#plan), 403 insufficient_scope / forbidden_channel, 404 user_not_found — the "to" username doesn't exist (includes a human-readable "detail"), 422 missing_target, 429 rate_limited).

## Pages

- https://pingwire.dev/ — overview
- https://pingwire.dev/developers.php — full API docs with copy-paste examples (curl, Bash, Python, Node, PHP)
- https://pingwire.dev/faq.php — frequently asked questions
- https://pingwire.dev/about.php — what Pingwire is and how it works
- https://pingwire.dev/pingwire-vs-telegram — Pingwire vs Telegram: when to use browser web push vs a Telegram bot for notifications (fair, factual comparison)

## Feature list

REST API · incoming webhooks · CLI · one-off & recurring reminders · channels and 1:1/group chat · real-time delivery with typing and read receipts · web push (PWA) · scoped API keys · bot identities · managed cloud service (also self-hostable).