Muster Bridge protocol (1.0.0)

Muster calls it on every Connection check, and again before a call when its copy is older than a few minutes. A bridge whose features change — buttons switched on, a new limit — is picked up without a restart of Muster.

Posts a Root message, a Storm summary or a test message. notify: true is a Loud message: it should notify people as the messenger's new messages do, and carries the envelope's Mentions. A Quiet message (notify: false) is sent without a notification where the bridge declares quiet_messages, and otherwise as an ordinary message without Mentions. The answer names the message for later edits and Thread replies; it may also return the thread_ref of its Thread when the messenger's Thread id is known at once. A replayed answer is followed by an editMessage of Muster's current state.

Replaces the whole message — text, colour and buttons — with the envelope; an empty buttons removes them. Edits are always Quiet and never carry Mentions, so the envelope has neither. Editing to the state the message already shows is a success. A message that no longer exists is gone; an edit that the messenger refuses because the message is older than it allows is gone with the reason edit_window_closed. Muster stops editing a message once it is older than limits.edit_max_age_seconds, less a safety margin.

Offered when capabilities.delete is declared. Muster L1 never deletes messages; the operation is reserved so that a later version of Muster can remove its test messages without a new protocol version. A message that no longer exists is a success.

Posts a reply in the Thread of the message message_id, usually a Root message. Muster sends the last thread_ref it received for that message — from postMessage or from an earlier reply — or null when it has none: the bridge then creates the Thread if its messenger needs that. It returns a thread_ref, which Muster stores and sends with the next reply of the same Thread, so the bridge needs no store of its own that maps messages to Threads. A thread_ref is opaque to Muster; it may equal the message id. A Thread that no longer exists, or a message that was deleted, is gone. Replies may carry buttons, such as "Still on it" on a Reminder, when the bridge declares buttons.

The Destination check. It must not post anything. Answer 200 only when the bot can post, edit its own messages and reply in Threads there; answer forbidden with a detail a person can act on — "The bot is not a member of this channel." — when the channel does not exist or the bot cannot use it. Muster runs it when a Destination is saved, when a person presses "Check", and every few minutes while the Destination is Broken.

Offered when user_lookup is not none. Muster calls it when a person asks to link an account by a code and enters their handle — an email address, a login, a username or a user id, as user_lookup declares. The answer lists the one account with that handle, or none. A handle the bridge cannot search for is invalid.

Offered when capabilities.direct_messages is declared with bot_can_start. Muster uses it to send the code of an Account link to the account a person named in their Muster profile. The bridge opens the direct chat if needed. An account that cannot receive a message from the bot is forbidden.

Muster's answer to a press, a Text command or an Account link request: a refusal, "Done: Acknowledged #42", "Linked to Muster user …". The bridge shows text to the person who caused the event event_id and says where: an answer to a press privately when its messenger allows that (private_answers) and the press is recent enough, otherwise in the Thread of the message; an answer to a thread_message in that Thread, never as a pop-up; an answer to an account_link in the direct chat it came from. Muster calls it within a few seconds of receiving the event and before acknowledging it, or not at all; an event the bridge no longer knows, or can no longer answer anywhere, is gone.

Offered when event_delivery contains push and chosen on the Connection. The bridge posts each event, one per request, to the callback address that the Bridge Connection shows in Muster: <MUSTER_INGEST_URL>/api/v1/callbacks/bridge/<connection id>.

The request is signed as Standard Webhooks specifies, with the Connection's push secret (whsec_ followed by the base64 of at least 24 random bytes, configured in both Muster and the bridge): webhook-id is the event's id, webhook-timestamp the Unix time of the attempt in seconds, and webhook-signature is v1, followed by the base64 of HMAC-SHA256 over <webhook-id>.<webhook-timestamp>.<body> with the decoded secret. Muster refuses a timestamp more than 5 minutes away from its own clock.

Muster answers 204 once it has handled the event, and also for an event id it has handled before. 400 means the event can never be handled — the bridge drops it. 401 means the signature, the Connection or its mode is wrong; the bridge keeps the event and retries after fixing its configuration. On any other answer or a timeout the bridge retries with backoff, for at least one hour, keeping the same webhook-id.

Offered when event_delivery contains poll. Returns the events after cursor — all of them when cursor is absent — oldest first, at once when there are any, otherwise as soon as one arrives or after wait seconds with an empty list; Muster waits for the answer up to wait plus 15 seconds. Muster handles the batch and sends next_cursor with its next call, so an event is delivered at least once; the bridge may then forget the events before that cursor. The bridge keeps events that Muster has not passed for at least 24 hours. A cursor the bridge no longer knows is invalid, and Muster polls again without one. Only one Muster replica polls a Connection at a time, but after a handover two calls may overlap; events are deduplicated by id.