Receive Your First Message
Step-by-step guide to receiving messages, downloading payloads, and verifying delivery through agrirouter
After sending your first message, the next step is receiving it on the other side. This page walks through listening for events, downloading the payload, and verifying delivery.
Prerequisites
Before you begin, make sure you have:
- An active endpoint with capabilities configured (see Your First Endpoint)
- A valid access token from the client credentials flow
- A message already sent to your endpoint (see Send Your First Message)
- Your environment URLs (see Environment URLs)
Receiving a message
Listen for events via SSE
Events about message activity are delivered through Server-Sent Events (SSE). To receive events, open a long-lived connection:
Opens an SSE stream that delivers events for every endpoint your application is authorized for. Each event is a type label plus a JSON data line.
Each event tells you that a message has arrived in your endpoint's feed, the per-endpoint queue where agrirouter stores received messages until you confirm them (see Feed Management). The payload_uri field contains the URL to download the payload.
For the full field list on every event type, see SSE Events.
Download the payload
Once you receive a message event, download the actual payload by making a GET request to the payload_uri from the event:
GET https://api.agrirouter.com/payloads/e4f5a6b7-c8d9-0123-4567-89abcdef0123/2026-03-20T10:30:01Z
Authorization: Bearer eyJhbGciOiJFUzI1NiIs...The response contains the message payload as a binary stream (application/octet-stream) in its original format. For the example above, this would be a ZIP file containing ISO 11783 TaskData.
payload_uri links expire after at most 15 minutes. Download the payload as soon as you receive the event. If the link expires, the only recovery path is to reconnect to the SSE stream so agrirouter replays the unconfirmed event with a fresh URL.
The payload_uri is pre-signed, so the download request does not need an Authorization header.
For small payloads, the event may include the data directly in the payload field (base64-encoded) instead of payload_uri. Only one of the two will be present. When payload is included inline, no separate download is needed.
Verify receipt
Confirm that the complete flow worked:
- Sender side: the
POST /messagesrequest returned200, confirming agrirouter accepted and routed the message. This is the only feedback the sender gets; there is no delivery confirmation event. - Receiver side: you received a
MESSAGE_RECEIVEDevent with the correct metadata. - Payload: the downloaded content matches what was sent.
If you are using the IO-Tool as the receiving endpoint, you can also verify receipt on the IO-Tool side by checking its received messages.
What you have accomplished
You have completed the full agrirouter message lifecycle:
- Sent a message from your endpoint
- Received events via SSE
- Downloaded the message payload
- Verified successful delivery
This is the pattern every data exchange through agrirouter follows, whether the payload is task data, machine descriptions, images, or telemetry.
Handling intermittent connections
Server-Sent Events are the only way to receive messages and events from agrirouter. There is no polling API, no webhook callback, and no push-notification fallback, so your application has to consume the SSE stream, either by keeping it open continuously or by reconnecting periodically.
An always-open stream is simplest, but many integrations cannot hold a long-lived connection: batch jobs, mobile clients, and processes that cycle through restarts. For those cases, the gateway performs a feed stream replay on reconnect. When you open a fresh SSE connection to GET /events, the gateway first replays every unconfirmed event that arrived on your endpoints while you were disconnected, then continues with live events. You do not need to track a cursor or query a separate endpoint; reconnecting is enough to catch up.
Confirm each event after your application has processed it by calling POST /confirmations. Confirmed events drop out of the replay, so the next reconnect only replays genuinely missed events instead of everything since the endpoint was created.
Next steps
For advanced messaging patterns and error handling, see the integration guide.
Sending and Receiving Messages6 minFor a conceptual overview of how messaging, routing, and subscriptions work together, see the messaging concepts page.
Messaging Concepts9 minChoose your integration path
Now that you have completed the Getting Started pages, continue with the integration guide for your endpoint type:
Cloud Software
Cloud-hosted applications acting on behalf of end users, including farm management software and telemetry backends. Register endpoints as `cloud_software`.
Virtual Communication Units
Per-machine endpoints for tractors, implements, and other ISOBUS machines managed from a cloud platform. Register each machine as a `virtual_communication_unit`.
Communication Unit (Legacy API)
Physical hardware devices like terminals or telemetry boxes that connect directly to machines over the legacy API.