PingRoom

Read back the current state of a live stream you created, so a restarted producer can reconcile instead of starting a duplicate. Only returns streams started by this credential, within the last 24 hours. Returns notification_id and correlation_id, then the stored display state (state, progress, message, category, template, accent_override, eta_at, deadline_at, duration_seconds, metrics, prompt, options, left, right, center, steps, current_step), action_state, and updated_at. Fields you never set come back as null rather than being omitted, so a matchup/metrics/countdown/question stream can be …

Fetch one visible ping by notification id, including its current action_state and, once anything on its data.checklist is checked, checklist_state.

Fetch the current state of a question without blocking.

Fetch a single room by its invite code, including members and quick actions.

Join a room using its invite code. Include the password only if the room is protected.

List a bounded page of this agent's Handoffs, newest first. Omit state (or use open) for unresolved work; use all for history and page while has_more is true.

List a bounded page of recent pings across approved rooms, newest first. Use page to continue while has_more is true.

List a bounded page of questions you asked, newest first. Optionally filter by state; use page while has_more is true.

List the quick actions configured for a room.

List the room-icon catalog (icon ids, tags, and categories). Call this before create_room / create_public_room / create_webhook to pick a valid icon id, and to interpret icon values returned by reads.

List the rooms the authenticated account belongs to.

List the incoming webhooks (with their trigger URLs) for a room the account owns.

Start, update, or end a live progress card on the room members' lock screen (an iOS Live Activity / Android live update). Reuse the same correlation_id for every ping of one stream: the first ping starts the card and sends one alert, further "running" pings move it silently, and the first "done"/"failed" sends one completion alert and ends it. Free accounts get a small number of NEW streams per day; updates and the final ping of an open stream are never charged; a first ping that is already "done"/"failed" counts as a new stream.

Ask the human to approve or reject an action, then block on their answer (pair with wait_for_approval). Delivered as a push to the connected human only, so like a direct ask_question to them it needs no trigger permission in the room; public and personal rooms are refused. Rate-limited.

Rotate this agent's public handle — kill-switch for a leaked handle.

Set this agent's avatar. Must be one of the PingRoom bot avatars.

Press a room quick action, notifying its members. Rate-limited. Read the action's input_type first (list_quick_actions): location needs data.location, link needs data.url, file/photo/pdf need attachment_ids — a press without the matching detail is a 422 quick_action_input_required. In someone else's personal room is_urgent and requires_ack are ignored; only the owner's own setting on the action applies.

Configure a numbered quick-action slot for a room the account owns. Sends a background room refresh to room members' devices.

Configure several of a room's quick-action slots in one call. Prefer this over repeated update_quick_action: each single-slot write wakes room members' devices with its own background refresh, so setting up four Pings one at a time spends four of a finite daily push budget on one operation. Slots you do not list are left exactly as they are, so this is also the right tool for editing a single Ping.

Update an incoming webhook (by id) on a room the account owns — e.g. change its icon, title, message, or sound.

Upload a small file (max ~90 KiB over MCP; Pro account required) and get an attachment id to include in broadcast or ask_question via attachment_ids. Larger files: use the PingRoom CLI or agent REST API.

Long-poll a generic acknowledgement-required ping until its confirmation rule is met (any: first confirmation; all: every original eligible recipient), it expires, or the timeout elapses. Questions use wait_for_answer instead.

Long-poll a question until it is answered or expires. Returns the state and, once answered, the chosen option value + label and the responder.

Long-poll an approval request until the human decides or it expires. Returns the status and, once decided, the chosen option.

Long-poll a Handoff until the human resolves it, it expires, or the bounded timeout elapses. For the onboarding Question returned by activate_agent_inbox, success requires an answered result with activation_completed true; use a bounded local deadline and treat any terminal answer without that stamp as incomplete.

Long-poll for the next ping. Blocks until one arrives or the timeout elapses — the real-time inbound channel for an agent. The agent's own sends are excluded.