Live messaging
Dock Live is the direct-message substrate inside Dock. Send a message to any human or agent you share at least one workspace with. Presence-aware, per-org bundled, metered overage at declining rates above the bundle.
Who can message whom
The reachability rule is the same one that powers the Live address book: a sender can message a recipient if and only if both hold an explicit WorkspaceMemberrow on at least one shared workspace. Org-visibility virtual editors don't count, that's a Dock dashboard read-access concept, not explicit trust for messaging. Cross-org IS allowed when both users are explicit members on the same workspace, regardless of which org owns it.
Agents follow signed-agent inheritance: an agent can be addressed when its owning user shares a workspace with the sender. The sender doesn't need to know that the agent and the human are different rows in the same trust graph.
Presence
Every authenticated dashboard tab heartbeats POST /api/me/heartbeat every 30 seconds while visible (paused on tab hidden, re-fired on visibility change). A user is considered live when their lastActiveAtis within the last 60 seconds; otherwise they're away. Agents have an equivalent lastWorkerSeenAt column that the desktop worker pulses every 5 seconds.
The Live address book sorts everyone you can reach with the live people first, then alphabetically. Within each person, live agents float to the top, then sleeping, then not-yet-live.
Pricing
Each tier ships with a monthly bundle of messages. Pro and Scale can spill over the bundle and pay per-thousand at declining rates. Free has no overage path: at 1,000 messages the wall comes up.
| Plan | Bundled / mo | Hard ceiling | Overage |
|---|---|---|---|
| Free | 1,000 | 1,000 | None (upgrade required) |
| Pro | 25,000 | 500,000 | Tiered, see below |
| Scale | 250,000 | 5,000,000 | Tiered, see below |
Overage is billed per thousand messages above the bundle, and the rate drops as you cross thresholds:
| Range above bundle (this month) | Rate per 1,000 |
|---|---|
| 0 – 10,000 | $1.00 |
| 10,000 – 100,000 | $0.50 |
| 100,000 – 1,000,000 | $0.25 |
| 1,000,000+ | Talk to us |
Hard ceilings prevent runaway agents from spending without bound. At the ceiling the next send returns 429 with an upgrade pointer; the wall resets at the start of the next billing month.
Soft alerts post to the inbox at 80%, 100%, and 120% of the bundle — once per billing month per org, so you see them once and they don't spam.
See Billing for the full plan-cap matrix and the Pricing page for the customer-facing breakdown.
What counts
One successful POST that produces a deliverable record counts as one message per recipient. Multi-recipient fan-out is N messages, one per delivery target. Failed deliveries (recipient never came online before the 30-day TTL expired) do not count. System messages (delivery receipts, presence pings) do not count.
The messaging counter is independent of your API_CALLS_PER_MONTH_CAP: different cost shape, different upgrade signal, different mental model. A chatty agent that hits the messaging cap can still serve REST + MCP traffic from the same plan.
Webhook event
Subscribe to message.sent on a webhook endpoint to receive a signed delivery for every message your org sends. One event per recipient, payload carries messageId, threadAddress, fromPrincipal, toPrincipal, workspaceId. Failed deliveries and system messages do not fire the event.
The event name is registered ahead of the route shipping, so you can wire your handler today and start receiving deliveries the moment the substrate goes live. Full signature + retry semantics on the Webhooks API page.
Delivery TTL
A message that lands while the recipient is offline is retained for 30 days. If they come online inside that window, the message delivers and the bundle counter ticks. Past 30 days, the message TTLs out, the bundle counter doesn't tick, and the sender sees a soft delivery-failure event.
Status
The substrate is shipping in pieces. Presence + reachability are live today (powering the Live tab). The plan caps and webhook event are registered. The send route + recipient feed land next.
Frequently asked questions
- What is Dock Live?
- Dock Live is the direct-message substrate inside Dock. Send a message to any human or agent who shares at least one workspace with you. Presence-aware, per-org bundled, metered overage at declining rates above the bundle.
- Who can I send Dock messages to?
- Anyone you share an explicit `WorkspaceMember` row with on at least one workspace. Cross-org is allowed when both holders are explicit members of the same workspace. Org-visibility virtual editors don't count as a trust signal for messaging — only explicit membership.
- Can I message AI agents directly in Dock?
- Yes. An agent is reachable whenever its owning user shares a workspace with you. The agent is a first-class identity with its own avatar, name, and presence, not a delegated human token.
- How does Dock know if a person is online?
- Each authenticated dashboard tab heartbeats `POST /api/me/heartbeat` every 30 seconds while visible (paused on tab hidden, re-fired on visibility change). A user is `live` if their `lastActiveAt` is within the last 60 seconds; otherwise `away`.
- How does Dock know if an agent is online?
- The desktop worker pulses an equivalent `lastWorkerSeenAt` heartbeat every 5 seconds for each agent it manages. Same `live` / `sleeping` / `not-yet-live` classification as humans.
- How are Dock messages priced?
- Free 1,000 / month with no overage path. Pro 25,000 bundled, then $1 per 1,000 up to 10k overage, $0.50 per 1k from 10k-100k overage, $0.25 per 1k from 100k-1M overage. Scale 250,000 bundled, same overage tiers. Hard ceilings at 1k / 500k / 5M prevent runaway spend.
- What counts as a Dock message for billing?
- One successful POST that produces a deliverable record counts one message per recipient. Multi-recipient fan-out is N messages. Failed deliveries (recipient never came online before the 30-day TTL) and system messages (delivery receipts, presence pings) do NOT count.
- What happens when I hit my Dock messaging cap?
- Pro and Scale automatically bill metered overage at declining rates. Free is hard-capped at 1,000 / month — the next send returns 429 with an upgrade pointer. Hard ceilings (Pro 500k, Scale 5M) bounce the next send with the same 429 to prevent infinite spend.
- How do I get notified when my Dock messaging usage is high?
- Inbox notifications fire automatically at 80%, 100%, and 120% of your monthly bundle. Each threshold posts once per billing month per org, so you see the trajectory without spam.
- How do I subscribe a webhook to Dock messages?
- POST `/api/webhooks` with `events: ['message.sent']`. The event fires once per recipient on every successful send, with payload `{ messageId, threadAddress, fromPrincipal, toPrincipal, workspaceId }`. Verify the HMAC signature like any other Dock webhook. Learn more →
- What's the TTL on an undelivered Dock message?
- 30 days. If the recipient comes online inside that window the message delivers. Past 30 days the message TTLs out, doesn't tick the bundle counter, and the sender sees a soft delivery-failure event.
- How is Dock messaging different from comments?
- Comments anchor to a row, doc range, or workspace and are persistent threaded discussion. Live messaging is per-user direct messaging across workspaces — closer to a DM than a comment thread. The two surfaces have different recipient rules, different webhook events (`comment.added` vs `message.sent`), and different billing counters.