Replies & callbacks

These endpoints let your program read what the user typed into a banner, and this page also documents the request Herald sends to your server when a callback button is pressed. Together they are the two ways a notification becomes a conversation. The examples use the $HERALD and $TOKEN variables from Connect.

Two ways to hear back#

A banner can carry buttons, and the user's choice has to reach your program somehow. Herald offers two paths, and which one you use depends on whether your program can receive HTTP requests.

A reply comes from a button of kind reply, which swaps the banner's buttons for a text field. The text is kept on the notification's History record and added to a queue for the app. The queue holds the 200 most recent replies of each app.

Pressing a reply button turns the row of buttons into a text field. What the user sends is what these endpoints return.

Endpoints#

GET /v1/replies#

Returns the replies waiting in the queue, oldest first. Use it to poll for answers to several notifications at once.

Request

curl -s "$HERALD/v1/replies?app=example.bidbot&consume=true" -H "Authorization: Bearer $TOKEN"

{
  "count": 1,
  "replies": [
    {
      "notificationId": "bid-42",
      "app": "example.bidbot",
      "title": "Counter-offer from Acme",
      "text": "Accept if they include delivery.",
      "repliedAt": "2026-10-02T13:04:41.526Z"
    }
  ]
}

Response fields

Errors

Notes

• Without consume=true a reply stays in the queue and is returned again by the next request.
• A reply removed from the queue is still on its History record.

GET /v1/replies/wait#

Waits until one notification has been answered, then returns the reply. The request stays open for up to the timeout you give, so you do not have to poll. Use it right after sending a question.

Request

curl -s "$HERALD/v1/replies/wait?id=bid-42&app=example.bidbot&timeout=120" \
  -H "Authorization: Bearer $TOKEN"

{
  "replied": true,
  "reply": {
    "notificationId": "bid-42",
    "app": "example.bidbot",
    "title": "Counter-offer from Acme",
    "text": "Accept if they include delivery.",
    "repliedAt": "2026-10-02T13:04:41.526Z"
  }
}

When the timeout passes with no reply, the status is still 200:

{"replied": false, "timedOut": true, "waitedSeconds": 120}

Response fields

Errors

Notes

• A reply that already exists is returned at once.
• Set your HTTP client's own timeout above the timeout you send, or the client gives up first.

Callback request#

This is not an endpoint you call. It is the request Herald sends to your server when the user presses a button of kind callback, or sends a reply from a reply button that has a callback.

Herald posts to the url of the button's callback, or to the callbackURL the app registered with POST /v1/register when the button names none.

Request

POST /herald HTTP/1.1
Host: 127.0.0.1:5123
Content-Type: application/json
X-Herald-Attempt: 1

{"notificationId": "bid-42", "app": "example.bidbot", "action": "Accept", "payload": {"decision": "accept"}}

Example response

Answer with any 2xx status once the action has happened. The body is ignored.

HTTP/1.1 204 No Content

Notes

• Herald adds two things to payload when they apply: the text of a reply as payload.reply, and the values a template attached to the button as payload.extra.
• A 2xx answer dismisses the banner. Any other outcome leaves the banner up and shows that the action failed.
• Each attempt may take 5 seconds. Herald retries once after a network error or a 408, 429 or 5xx status. Use notificationId and action to ignore a repeat.
• Redirects are never followed.
• A callback URL on this Mac (127.0.0.1, localhost, ::1) needs no approval. Any other host must be approved by the user the first time.

How callbacks fit with the other action kinds, and what the user is asked, is in the actions reference.

Related#

• Two-way notifications: build a banner that asks a question and act on the answer.
• Actions reference: every action kind, including reply and callback.
• Notifications API: the button object.
• MCP tools for notifications: get_replies and wait_for_reply for an agent.