Sending Structured Pings From Agents

The difference between a notification and an agent-ready Ping is structure.

A human needs a title, message, room, sound, and action context. A machine also needs identifiers. It needs to know which workflow produced the Ping, how to match the response, and what state should be carried forward. That is why PingRoom supports structured Pings.

The fields are intentionally small:

data
correlation_id
reply_to

Together they let an agent send a human-readable signal while preserving machine-readable context.

Basic Payload

An agent broadcast can look like this:

POST /api/agent/rooms/{inviteCode}/notifications
Authorization: Bearer AGENT_TOKEN
Content-Type: application/json

{
  "message": "Production deploy is waiting for approval.",
  "correlation_id": "deploy-2026-06-07-001",
  "reply_to": "workflow:release:prod",
  "data": {
    "environment": "production",
    "commit": "abc123",
    "pipeline_url": "https://ci.example.com/runs/42"
  }
}

The human sees the room Ping. The agent, outgoing webhook receiver, or later approval flow can match the event by correlation_id.

Data Rules

data should be a JSON object, not a list or scalar.

The current system treats structured data as bounded context, not arbitrary storage. Keep it short, stable, and designed for machines:

{
  "ticket_id": "SUP-1042",
  "priority": "high",
  "customer_tier": "pro"
}

Avoid sending large logs, stack traces, full documents, or private secrets. If the human needs a lot of detail, send a link in the message or data payload and keep the Ping itself compact.

Push Payload Discipline

Stored data and push data are not the same thing.

PingRoom can store a larger structured object than it should send through APNs or FCM. APNs has a strict payload ceiling, and FCM data values have their own shape constraints. The platform therefore needs to include structured data in the push only when it is safe, while keeping the full record available through read surfaces.

As an integration author, design for that reality. The notification should be useful even if the push payload only carries the essential identifiers.

Correlation IDs

correlation_id is the most important field for workflow continuity.

Use a value generated by the outside system:

deploy:prod:2026-06-07T14:22Z
github:run:998812
agent-task:01HZ...

The value should be stable across retries. If the same workflow sends a Ping twice, the correlation id helps receivers understand whether those Pings are related.

Reply Pointers

reply_to is useful when the receiving system needs to route the next event.

It can point to a workflow, task, thread, or callback concept. It should not replace correlation_id; it complements it. Think of correlation_id as the event match key and reply_to as routing context.

Where Structured Pings Flow

Structured fields should appear consistently across:

• agent broadcasts
• agent direct messages
• incoming webhooks
• room notification records
• APNs/FCM custom data when size allows
• agent listen/list endpoints
• outgoing webhooks
• approvals and Question results

That consistency is what lets PingRoom become a fabric instead of a pile of disconnected alerts.

The Integration Principle

Write the human text for the person and the structured fields for the machine.

Do not make humans parse JSON. Do not make agents parse prose. A good PingRoom Ping gives both sides exactly what they need.