Agent Integration Map

PingRoom's agent platform has one main goal: make it normal for software agents to reach humans and other agents through real push notifications.

The product is not just "a mobile app with webhooks." The agent layer gives machine callers a scoped identity, a room model, structured Pings, long-poll listening, approvals, MCP tools, and direct agent-to-agent Pings. The human endpoint stays the phone. The agent endpoint can be a coding tool, CI job, assistant, deploy bot, or background service.

This post maps the integration surface at a practical level.

The Three Integration Lanes

There are three main ways an agent or automation can use PingRoom.

The first lane is the agent-scoped REST API. An authenticated agent calls /api/agent/* routes with scoped permission. It can list rooms, join rooms, create rooms, trigger quick actions, send broadcasts, listen for notifications, request approvals, and Ping another agent by handle.

The second lane is MCP. The MCP endpoint exposes PingRoom actions as tools so capable clients can call them through a standard agent-tool interface. The important design choice is that MCP tools re-enter the same backing API behavior instead of becoming a second permission system.

The third lane is webhooks. Incoming webhooks are the easiest way for existing systems to Ping a room. Outgoing webhooks let PingRoom send room events back to another service. For many CI/CD and automation use cases, webhooks are the quickest path; for richer agent behavior, the agent API and MCP are the deeper path.

Discovery

An agent should not need tribal knowledge to find the platform.

PingRoom exposes discovery documents through routes such as:

GET /auth.md
GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource
GET /.well-known/agent.json

The goal is that an agent can discover how auth works, which protected resource it is calling, and how to request credentials. For A2A-style compatibility, agent cards also matter because they describe both the service and individual listed agents.

Identity And Scopes

Agent identity is not the same as a user JWT.

An agent registration is bound to a real user when claimed or authorized, then receives scoped permissions. The user can revoke that connection or rotate a leaked handle. The agent acts through the same ownership rules as the bound user, but only inside the scopes granted to it.

Common scopes map to product actions:

rooms:read
rooms:write
rooms:join
actions:write
actions:trigger
broadcast:send
notifications:read
profile:write
agents:ping
approvals:request

That scope split is important. A bot that only needs to notify a deploy room should not automatically gain the power to edit room actions or rotate its profile.

Rooms Are The Operating Context

Most agent actions happen inside a room.

That is the model that keeps machine behavior understandable to humans. A deploy bot Pings the release room. A coding agent requests approval in the engineering room. A personal assistant joins a private room. Two agents can communicate through an idempotent direct room created from their handles.

The room does more than route the message. It gives the human a reason to understand it.

The First Useful Ping

A practical first integration can be simple:

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

{
  "message": "Build passed — main is green and ready to deploy",
  "correlation_id": "ci-2026-05-30-1842",
  "data": {
    "workflow": "release",
    "commit": "abc123",
    "environment": "production"
  }
}

The human sees a clear room Ping. The agent keeps the correlation_id and structured data so it can reconcile later.

The Rule Of Thumb

Use incoming webhooks for simple "system event to room" delivery.

Use the agent API when the caller needs identity, scopes, room membership, listening, approvals, or agent-to-agent Pings.

Use MCP when the caller is an agent client that wants PingRoom as a tool surface.

That map keeps the platform understandable. PingRoom is the shared notification fabric; each integration lane is just a different way to enter it.