The Bridge Dispatch Payload#
A chat bridge never runs the agent. It fires one dispatcher webhook per question and posts back what comes out, so everything the agent learns about the conversation — the previous exchanges, the message being replied to, the files attached to either — arrives as fields of that one JSON body.
This page is that body. Read it if you are writing an adapter for a chat system OSPREY does not ship (Extending Osprey covers the seam itself), or if you are authoring a trigger prompt and want to know what is actually in front of the agent.
The request#
The bridge POSTs to <dispatcher>/webhook/<trigger> with a Bearer
token. The body is the question plus whatever context the engine assembled:
{
"question": "now plot that over 24 hours",
"asker": {"id": "users/111", "name": "Alice"},
"room": {"members": [{"id": "users/111", "name": "Alice"},
{"id": "users/222", "name": "Carol"},
{"id": "users/333", "name": null}],
"mentions": "To @mention a member of this room, write <@ID> ..."},
"conversation_so_far": [{"question": "...", "answer": "...", "ts": 1757000000.0,
"run_id": "run-...", "artifacts": [],
"asked_by": {"id": "users/222", "name": "Carol"},
"answer_chars": 4210}],
"prior_answer_runs": ["run-..."],
"reply_to": {"sender": "Alice", "text": "the vacuum trace from this morning"},
"input_files": [{"filename": "trace.png", "mime": "image/png",
"content_b64": "...", "ingest": true}],
"skipped_attachments": [{"filename": "scan.h5", "reason": "..."}]
}
Only question is always present. asker is present whenever the chat
system told the bridge who sent the message. A text-only message whose sender
is unknown, in a fresh conversation, sends question and nothing else. The
engine omits an empty context rather than sending empty containers.
The whole body becomes the agent’s context, exactly as it does for a webhook
fired by hand. A trigger’s prompt does not have to name these fields for the
agent to see them. Two fields are the exception: the dispatcher takes
input_files and prior_answer_runs out of the body and hands each to the
worker as a field of its own.
asker#
Who sent this message, as id (the chat system’s stable identity for the
person) and name (their display name). Either may be null when the chat
system did not supply it.
It is what the chat system reports, not a verified identity. The dispatcher folds the whole body into the agent’s prompt, so the agent reads the name the way it reads the question; what the agent may do is set by the trigger’s tool list, and that list, not the payload, is the security control.
room#
Who is in the conversation. Present only when the bridge can list the room (Google Chat, Microsoft Teams, Nextcloud Talk, and Slack outside one-to-one direct messages):
Field |
Meaning |
|---|---|
|
The chat system’s stable identity for the person, the same kind of
string as |
|
The name the chat system’s member listing gives; else a name the bridge
saw in that room (a sender, or someone mentioned in a message to it);
|
|
An instruction written for the agent: how to write |
|
|
The bridge renders <@ID> into its chat system’s own mention only for an id
in members. A mention of anyone not listed is posted as plain text.
conversation_so_far#
The recent exchanges in this conversation, oldest first. This is what makes “now plot that over 24 hours” resolve its referent. Each turn:
Field |
Meaning |
|---|---|
|
What was asked. |
|
What the agent replied. A turn whose run failed carries a marker here instead, so the referent survives even when the answer did not. |
|
Unix timestamp of the exchange. |
|
The dispatch run that produced the answer, or |
|
Descriptors for the files that run produced — round-tripped opaquely by the bridge, capped per turn, newest kept. |
|
Who asked this question, in the same shape as |
|
Present only when |
The bridge caps the list by turn count and by total serialized size, dropping oldest first, so the newest exchanges always survive.
A descriptor may carry a note reading "may have expired". That is the
bridge saying it could not bring the artifact’s bytes back — swept, deleted, or
too large for the budget below — so the agent should say the file is no longer
available rather than pretend to look at it. Nothing keys on the exact wording;
it is written to be read.
Shortened answers#
An answer longer than the bridge’s HISTORY_ANSWER_LIMIT (3000 characters by
default) is sent as its opening and a note naming its run. The agent reads the
whole answer with prior_answer_read. The agent record keeps every answer
in full, once, in the run that gave it. Against a dispatcher or worker that
does not advertise prior_answers, every answer is sent in full.
prior_answer_runs#
Present only when an answer was shortened: the run ids of those turns. The
worker lets prior_answer_read read those runs and no others.
conversation_record#
Present only when this conversation’s history is missing from the payload, and
says why. The bridge reads conversation_so_far back from the agent record;
when that read does not come back whole, the bridge sends no history at all
rather than part of it, and sets this key:
Value |
Meaning |
|---|---|
|
The record did not answer the read: it was unreachable or refused it. |
|
The record answered, but marked its answer incomplete. |
Absent when the history read was complete, including a conversation that has
no earlier turns. The key tells the agent that earlier turns may exist but
were not sent, so a question that refers back (“that plot”, “the same
channel”) may have a referent it cannot see. How far back a conversation can
be replayed at all is agent_record.retention_days.
input_files and skipped_attachments#
Files ride the payload as base64, in one list:
Field |
Meaning |
|---|---|
|
The name the agent sees. |
|
The type the adapter fetched it as. |
|
The bytes, base64-encoded. |
|
|
Order is fixed: this message’s own attachments, then the quoted message’s, then any replayed prior images. Replay exists so a follow-up about a plot can look at the plot again rather than only at its descriptor; replayed bytes are deduplicated by content against what the message already attached.
Two budgets bound the list, both enforced by the bridge before anything is sent:
Fresh files — at most 5 files and 10 MiB across
ingest: trueentries, own attachments first.Replayed images — at most 3 images and 8 MiB, newest first, and only images.
skipped_attachments accounts for everything that did not make it, as
{"filename": ..., "reason": ...} notes the agent can relay. The reasons the
engine itself writes:
Reason |
When |
|---|---|
|
The count budget was already spent. |
|
The byte budget was already spent. |
|
The worker on the other end does not advertise |
An adapter adds its own reasons for what it could not fetch — a download that failed, a type the chat system will not hand over — in the same shape.
See also
- Chat Bridges
What a bridge is, what it remembers, and who can ask it questions.
- Event Dispatch
The dispatcher and worker on the receiving end of this payload, and how to write the trigger it fires.