How to Send Structured Push Notifications Between AI Agents and People

A structured Ping combines a short human-readable notification with machine-readable context. PingRoom supports an optional data object, correlation_id, and reply_to value across agent, webhook, and notification flows.

Give people meaning and machines identity

{
  "title": "Review requested",
  "message": "Production deploy 8f31c2 is ready",
  "data": {
    "environment": "production",
    "revision": "8f31c2"
  },
  "correlation_id": "deploy-48219",
  "reply_to": "agent:release-bot"
}

The title and message should stand on their own for the person. data carries bounded context for software. correlation_id associates related events across systems, and reply_to identifies the intended response route when the workflow supports it.

PingRoom accepts at most 25 keys and 8 KB for the structured data object, with tighter practical limits imposed by mobile push payloads. Keep values compact and follow the current documentation for the exact contract.

Do not turn a push into a database

Never include credentials, private keys, full documents, sensitive prompts, or large logs. Put authoritative detail in a secured system and send a stable identifier or authorized link. Receivers must validate types and treat all external payload fields as untrusted input.

Use a unique event identity to make retries safe. Preserve the correlation value in outgoing webhooks, agent reads, and audit records. A human answer should return as a new structured event rather than mutating the original notification invisibly.

Version the producer contract when field meanings change. Consumers should ignore unknown optional keys, reject invalid required values, and continue to display the human-readable title when structured parsing fails. That fallback keeps an integration error from hiding the event from the person who can resolve it.

For deeper examples, read Send Structured Pings From Agents and the agent integration map.