Notifications

One-shot push notifications to every device signed in to your Chirp account. No persistent card, no lifecycle — just a title, a body, and optional rich fields like images, sounds, and tap-to-open URLs.

Quick start

The simplest way to send a notification is a single HTTP request. Replace $CHIRP_API_KEY with your API key from the dashboard.

shell

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello from Chirp","body":"Your first notification!"}'

Every SDK and integration wraps this endpoint. See the integrations page for language-specific examples — use the Live Activity / Notification toggle on each integration page to switch between the two modes.

Notifications vs Live Activities

Notification

Fire-and-forget — no lifecycle to manage
Supports images, sounds, subtitles, tap-to-open URLs
Groups via thread_id in Notification Center
Best for: alerts, one-time events, status updates

Live Activity

Persistent card on the lock screen and Dynamic Island
Start → update → end lifecycle
Rich template layouts (@deploy, @agent, @training, etc.)
Best for: long-running tasks, builds, training runs, monitoring

Schema reference

POST to /v1/notify with a JSON body containing any of these fields.

titlerequired

string

First line of the notification. Max 200 characters.

bodyrequired

string

Primary content of the notification. Max 4000 characters.

subtitle

string

Line displayed below the title in smaller text. Useful for source or category labels.

sound

string

Use "default" for the standard iOS notification sound, or the name of a custom sound bundled in the app (e.g. "chirp"). Omit to use the default sound.

image_url

string (URL)

Link to an image (JPEG, PNG, or GIF, under 10 MB). The image is downloaded and displayed as a rich notification attachment. Requires the Chirp app to have the Notification Service Extension installed.

open_url

string (URL)

URL to open when the user taps the notification. External URLs open in the browser; deep links (chirp://) route inside the app.

thread_id

string

Groups related notifications together in Notification Center. Use consistent thread IDs to bundle notifications (e.g. all deploy alerts under "deploys").

interruption_level

string

Controls how urgently the notification is delivered. Options: "passive" (silent, no screen wake), "active" (default — sound + screen), "time-sensitive" (breaks through Focus and Notification Summary), "critical" (overrides mute, requires Apple entitlement).

volume

number (0–1)

Sound volume for critical alerts only. Only applies when interruption_level is "critical". Defaults to full volume (1).

filter_criteria

string

Matches a Focus filter configured on the device. If the active Focus allows this criterion, the notification can be shown.

data

object

Arbitrary key-value data passed to the app. Not displayed in the notification itself, but accessible in notification handlers.

priority

string

Delivery priority hint. "high" (default for notifications), "normal", or "default". High-priority notifications wake the device; normal may be batched.

Examples

Minimal notification

shell

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Deploy complete","body":"my-app v2.4.1 is live"}'

Rich notification with image and tap URL

shell

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New order",
    "body": "$129.99 from [email protected]",
    "subtitle": "Shopify",
    "sound": "default",
    "image_url": "https://cdn.example.com/product-thumb.jpg",
    "open_url": "https://admin.shopify.com/orders/12345",
    "thread_id": "orders"
  }'

Time-sensitive alert

Breaks through Focus and Notification Summary on the user’s device.

shell

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Server down",
    "body": "api-prod-3 is unreachable. Last ping 45s ago.",
    "sound": "default",
    "interruption_level": "time-sensitive"
  }'

Python SDK

python

import chirp

chirp.notify(
    title="Build complete",
    body="my-app v2.4.1 deployed to production",
    sound="default",
    thread_id="deploys",
)

# With all options:
chirp.notify(
    title="Payment received",
    body="$49.99 from [email protected]",
    subtitle="Stripe",
    sound="chirp",
    image_url="https://example.com/receipt.png",
    open_url="https://dashboard.stripe.com/payments/pi_123",
    interruption_level="active",
)

Node SDK

typescript

import { ChirpClient } from "chirp";

const chirp = new ChirpClient();

await chirp.notify("Build complete", "my-app v2.4.1 deployed to production", {
  sound: "default",
  thread_id: "deploys",
});

Bash helper

shell

source ~/.chirp.sh
chirp_notify "Deploy done" "my-app is live"

Sounds

The sound field controls what plays when the notification arrives.

"default"Standard iOS notification sound.
"chirp"Custom Chirp notification sound (bundled in the app).
omittedDefault notification sound.

Interruption levels

iOS lets you control how urgently a notification is presented. Set the interruption_level field to one of these values.

passive

Silently added to Notification Center. No sound, no screen wake, no banner. Use for low-priority informational updates.

active

Default behavior. Presents a banner, lights up the screen, plays the sound. This is what you get when you omit the field entirely.

time-sensitive

Breaks through Focus and Notification Summary. Use for alerts that need immediate attention — server down, deployment failures, security events.

critical

Overrides the mute switch and Do Not Disturb. Plays at the volume specified by the volume field. Requires the critical alerts entitlement from Apple — contact us to enable this.

Image attachments

Pass an image_url and the Chirp app’s Notification Service Extension will download the image and attach it to the notification. The image appears as a thumbnail that the user can expand with a long-press or 3D Touch.

Supported formats: JPEG, PNG, GIF (including animated GIFs)
Maximum size: 10 MB
The URL must be publicly accessible (no auth headers are sent)
Download must complete within 30 seconds (Apple’s limit)

Thread grouping

Set thread_id to group related notifications in Notification Center. All notifications with the same thread ID are bundled together — the user sees a stack instead of individual items.

Good thread IDs are stable, meaningful strings like deploys, orders, ci-main, or alerts-prod.

Tap-to-open URLs

Set open_url to open a link when the user taps the notification. External URLs (https://) open in the browser. The app’s internal deep links (chirp://) route to the appropriate screen.

Send notifications from…

Python SDK Node SDK Go SDK Ruby SDK Rust SDK CLI Bash helpers Raw HTTP / curl GitHub Actions n8n Zapier Home Assistant

Use the Notification toggle on each integration page to see the notification-specific setup.