Notification actions

A message notification can offer Reply and Mark as read. These two endpoints carry those out from the phone's notification code, usually while the app is not running and has no user session.

They take the reply grant from the notification push, not a user JWT:

Authorization: Bearer <reply_grant>

The reply_grant field of a message push names the user, the device and the conversation, and lasts 3 days. It can act only on that one conversation. Membership is still checked on every call: a user removed from the conversation since the push cannot use it. See Push payloads for where the grant appears.

Neither endpoint honours Idempotency-Key. Use the reply id instead.

Reply

POST/v1/notifications/reply

Reply grant

Sends a text message into the grant's conversation as the grant's user, then marks the conversation read for them.

Field	Type	Required	Description
`body`	string	yes	The reply text. Leading and trailing whitespace is trimmed. Must not be empty after trimming. Up to 64 KB.
`id`	uuid	no	Your own id for the message. Send the same `id` on a retry: if that message was already sent by this user in this conversation, you get it back with `200` instead of a second message.

Response

201 with the new message. 200 with the existing message when id matches one already sent.

curl -X POST https://api.poolse.dev/v1/notifications/reply \
  -H "Authorization: Bearer $REPLY_GRANT" \
  -H "Content-Type: application/json" \
  -d '{"body":"On my way","id":"9d2f6b1a-4c8e-4a3f-b7d0-1e5c9a2f4b68"}'

Errors

Code	Status	When
`unauthorized`	401	Missing, expired or invalid reply grant.
`user_blocked`	401	The grant's user has been blocked since the notification was sent.
`mau_cap_exceeded`	402	The user is new this month and the plan's monthly active users are full.
`forbidden`	403	The user is no longer a member, or your subscription is inactive.
`not_found`	404	The conversation no longer exists.
`validation_failed`	422	`body` missing or empty, or the message could not be sent. No `details`.
`bad_request`	400	`id` is not a valid UUID.

Mark read

POST/v1/notifications/read

Reply grant

Marks the grant's conversation read for the grant's user, up to its latest message. No body.

204 on success, also when the conversation has no messages.

Code	Status	When
`unauthorized`	401	Missing, expired or invalid reply grant.
`user_blocked`	401	The grant's user has been blocked since the notification was sent.
`mau_cap_exceeded`	402	The user is new this month and the plan's monthly active users are full.
`forbidden`	403	The user is no longer a member.
`not_found`	404	The conversation no longer exists.
`validation_failed`	422	The read position could not be saved.