# How to Send Structured Push Notifications Between AI Agents and People

> Add bounded JSON data, a correlation ID, and reply context to a human-readable Ping so software and people can share one event.

- Published: 2026-08-02
- Author: PingRoom
- Category: Agents
- Topics: structured push notifications for agents, AI agent notification JSON, machine readable human notifications
- Canonical: https://pingroom.io/blog/structured-push-notifications-for-agents
- Cover image: https://pingroom.io/blog/structured-push-notifications-for-agents.webp
- Cover description: Geometric red data packets flowing between an AI core and a human phone.

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

```json
{
  "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](/documents) 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](/blog/send-structured-pings-from-agents) and the [agent integration map](/blog/agent-integration-map).