Documentación de la API
Envía notificaciones push a tu iPhone desde cualquier servidor, script o pipeline de CI con una sola petición HTTP.
Inicio rápido
1. Abre Pling en tu iPhone. Ve a Config > Tokens y genera un token de API.
2. Envía tu primera notificación:
$ curl -X POST https://api.plingpush.com/api/push \ -H "Content-Type: application/json" \ -d '{"token":"YOUR_TOKEN","title":"Hello from Pling!"}'
3. La notificación llega a tu teléfono al instante mediante push o WebSocket.
URL base
https://api.plingpush.com
Todos los endpoints aceptan y devuelven JSON. Autentícate con tu token de API en el cuerpo de la solicitud o en la ruta de la URL.
Endpoints
Envía una notificación push JSON. Incluye tu token en el cuerpo.
Solicitud
{
"token": "YOUR_TOKEN",
"title": "Deploy complete",
"message": "Production v2.4.1 is live",
"channel": "deploys",
"priority": "normal"
}
Respuesta 200
{ "ok": true, "id": "notif_a7x9k2" }
El token se pasa en la ruta de la URL. Envía texto plano (el cuerpo se convierte en el mensaje) o JSON sin el campo del token.
# Plain text: body becomes the message curl -d "Server rebooted" https://api.plingpush.com/api/push/YOUR_TOKEN # JSON: token from URL, not body curl -X POST https://api.plingpush.com/api/push/YOUR_TOKEN \ -H "Content-Type: application/json" \ -d '{"title":"Alert","priority":"high"}'
Pégalo en un navegador, márcalo como favorito o úsalo en webhooks que solo admiten solicitudes GET.
https://api.plingpush.com/api/push/YOUR_TOKEN?title=Hello&message=World&priority=high
Parámetros de consulta: title (o t), message (o m), priority (o p), subtitle, sound.
Campos de la solicitud
| Campo | Tipo | Descripción |
|---|---|---|
| token obligatorio | cadena | Tu token de API |
| título obligatorio | cadena | Título de la notificación (máx. 512) |
| message | cadena | Texto del cuerpo (máx. 4096) |
| subtítulo | cadena | Línea de subtítulo (máx. 256) |
| channel | cadena | Nombre del grupo, p. ej. "deploys" |
| priority | cadena | low normal high critical |
| url | cadena | Se abre al tocar la notificación |
| image_url | cadena | URL de la imagen adjunta |
| sonido | cadena | Nombre de sonido (anula el predeterminado del canal) |
| thread_id | cadena | Agrupar en el mismo hilo de notificaciones |
| interruption_level | cadena | passive active time-sensitive |
| actions | array | Botones: [{label, url, method?}] |
| metadata | object | Datos clave-valor personalizados (máx. 2KB) |
| body | cadena | Alias de message (máximo 4096) |
| cifrado | boolean | Si es true, el título y el mensaje se cifran de extremo a extremo (Pro) |
Límite total de la carga útil: 64KB.
Niveles de prioridad
| Prioridad | Comportamiento |
|---|---|
low | Entrega silenciosa, solo aparece en el feed |
normal | Push estándar con sonido predeterminado |
high | Alerta destacada, resaltada en el feed |
critical | Omite el modo No molestar y el modo silencio |
Canales
Los canales agrupan las notificaciones por tema. Créalos en la app para establecer sonidos personalizados y horarios de silencio por canal.
Incluye "channel": "name" en tu solicitud. La notificación se entrega aunque el canal aún no exista en la app. Los ajustes simplemente no se aplicarán hasta que lo crees.
Límites de tasa
| Endpoint | Límite |
|---|---|
POST /api/push | 60 solicitudes/min por token |
GET /api/push/:token | 30 solicitudes/min por token |
Devuelve 429 Too Many Requests cuando se supera.
Errores
Todas las respuestas devuelven JSON:
// Success { "ok": true, "id": "notif_a7x9k2" } // Error { "ok": false, "error": "token and title are required" }
| Estado | Significado |
|---|---|
| 200 | Notificación enviada |
| 400 | Solicitud no válida (faltan campos, carga útil demasiado grande) |
| 401 | Token no válido o caducado |
| 403 | Se requiere suscripción Pro |
| 429 | Límite de tasa superado |
| 500 | Error del servidor |
Ejemplos de código
# Basic notification curl -X POST https://api.plingpush.com/api/push \ -H "Content-Type: application/json" \ -d '{"token":"YOUR_TOKEN","title":"Hello"}' # Full example with all common fields curl -X POST https://api.plingpush.com/api/push \ -H "Content-Type: application/json" \ -d '{ "token": "YOUR_TOKEN", "title": "Disk full", "subtitle": "db-01", "message": "/dev/sda1 at 95%", "channel": "alerts", "priority": "critical", "url": "https://grafana.example.com/d/disk" }' # Plain text via token-in-URL echo "Backup complete" | curl -d @- \ https://api.plingpush.com/api/push/YOUR_TOKEN
// Node.js / Bun / Deno const response = await fetch("https://api.plingpush.com/api/push", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ token: process.env.PLING_TOKEN, title: "Build failed", message: error.message, channel: "ci", priority: "high" }) }); const data = await response.json(); // { ok: true, id: "notif_..." }
import requests requests.post("https://api.plingpush.com/api/push", json={ "token": os.environ["PLING_TOKEN"], "title": "Training complete", "message": f"Loss: {final_loss:.4f}", "channel": "ml", "priority": "normal" })
var request = URLRequest( url: URL(string: "https://api.plingpush.com/api/push")!) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try JSONEncoder().encode([ "token": "YOUR_TOKEN", "title": "Backup complete", "message": "2.4 GB archived", "channel": "backups" ]) let (data, _) = try await URLSession.shared.data(for: request)
payload, _ := json.Marshal(map[string]string{ "token": os.Getenv("PLING_TOKEN"), "title": "Deploy complete", "channel": "deploys", "priority": "normal", }) http.Post("https://api.plingpush.com/api/push", "application/json", bytes.NewReader(payload))
# .github/workflows/deploy.yml - name: Notify Pling if: always() run: | curl -X POST https://api.plingpush.com/api/push \ -H "Content-Type: application/json" \ -d '{ "token": "${{ secrets.PLING_TOKEN }}", "title": "Deploy ${{ job.status }}", "message": "${{ github.repository }}@${{ github.sha }}", "channel": "deploys", "priority": "${{ job.status == 'failure' && 'high' || 'normal' }}" }'
#!/bin/bash # pling-notify.sh: save and chmod +x TOKEN="${PLING_TOKEN}" TITLE="${1:-Notification}" MSG="${2:-}" PRIORITY="${3:-normal}" CHANNEL="${4:-}" curl -s -X POST https://api.plingpush.com/api/push \ -H "Content-Type: application/json" \ -d "$(jq -n \ --arg t "$TOKEN" --arg title "$TITLE" \ --arg msg "$MSG" --arg p "$PRIORITY" \ --arg ch "$CHANNEL" \ '{token:$t,title:$title,message:$msg,priority:$p,channel:$ch}')" # Usage: ./pling-notify.sh "Deploy OK" "v2.4.1" "normal" "deploys"
# Crontab heartbeat every 6 hours 0 */6 * * * curl -s -o /dev/null \ "https://api.plingpush.com/api/push/YOUR_TOKEN?title=Heartbeat&m=Server+is+alive" # Docker healthcheck HEALTHCHECK --interval=5m CMD curl -sf \ "https://api.plingpush.com/api/push/YOUR_TOKEN?t=Health+OK" || exit 1
Configuración del agente de IA
Añade notificaciones de Pling a cualquier proyecto pegando esto en tu agente de programación con IA. Configurará un ayudante de notificación y lo llamará desde tus rutas de despliegue o de error.
Claude Code Añadir a CLAUDE.md
When you complete a task, send me a push notification:
curl -X POST https://api.plingpush.com/api/push \
-H "Content-Type: application/json" \
-d '{"token": "YOUR_TOKEN", "title": "Done", "message": "Brief summary"}'
For deploy scripts and error handlers in this project, use the
PLING_TOKEN environment variable and send push notifications on
success (priority: normal, channel: deploys) and failure
(priority: high, channel: alerts). Add a notify() helper if one
doesn't exist.
Claude Code lee CLAUDE.md al inicio de cada conversación. Añadir esto de forma global significa que cada proyecto recibe notificaciones de Pling automáticamente.
Codex Añadir a AGENTS.md
## Notifications
After completing tasks, send a push notification via Pling:
POST https://api.plingpush.com/api/push
Content-Type: application/json
{"token": "$PLING_TOKEN", "title": "Task complete", "message": "summary"}
For deploy and CI scripts, call this endpoint on success
(channel: deploys, priority: normal) and on failure
(channel: alerts, priority: high). Use the PLING_TOKEN env var.
Codex lee AGENTS.md para las instrucciones del proyecto. Esto garantiza que cada ejecución del agente de Codex te notifique a través de Pling al completarse.
Prompt de una sola vez (cualquier agente de IA)
Integrate Pling push notifications into this project.
API endpoint: POST https://api.plingpush.com/api/push
JSON body: {token, title, message?, channel?, priority?}
Token comes from PLING_TOKEN env variable.
Add a notify() helper function. Call it from:
- Deploy success path (channel: "deploys", priority: "normal")
- Error handlers (channel: "alerts", priority: "high")
- Long-running task completion (channel: "tasks")
Recetas
Guías paso a paso para enviar pushes de Pling desde las herramientas que ya usas:
- GitHub Actions — envía el resultado de una compilación a tu teléfono, con un enlace pulsable que te lleva de vuelta a la ejecución.
- Trabajos cron y scripts de shell — recibe un aviso cuando un trabajo programado o una copia de seguridad termina o falla.
- Python — un ayudante reutilizable, notify-on-exception y hooks para Django/Flask.
- Grafana — dirige las alertas de Grafana a tu teléfono mediante un punto de contacto de webhook.
- Prometheus Alertmanager — un webhook_config que envía las alertas activas y resueltas.
- Uptime Kuma — alertas de monitorización de actividad/inactividad como notificaciones push.