# Sending Structured Pings From Agents

> A practical guide to using data, correlation IDs, and reply pointers when agents send Pings.

- Published: 2026-06-07
- Author: Mahdi Salmanzade
- Category: Agents
- Canonical: https://pingroom.io/blog/send-structured-pings-from-agents
- Cover image: https://pingroom.io/blog/send-structured-pings-from-agents.webp

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:

```text
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:

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

```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`.

![](/blog/send-structured-pings-from-agents-1.webp)

## 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:

```json
{
  "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:

```text
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.