Notifications
One-way notices from your fleet to a chat destination: what they cost to turn on, and what they deliberately cannot do.
For whoever wires the fleet into a chat workspace — an operator or an integrator.
After reading it you can create the app, declare a binding and its credential, route notice types to it, and know which types you have routed nowhere.
Before you start: an installed fleet, and admin rights in the chat workspace you are wiring.
Saphan Studio can send a short notice to a chat destination when the fleet needs a human, or when a human decision has just been recorded. A notice is a message out. Nothing comes back through it, and no message posted into your chat workspace can change anything in the fleet.
In one paragraph
You create a chat app in your own workspace, tell Saphan Studio which conversation to deliver into and which credential to use — that pair is a binding — and then say which kinds of notice go to which binding — those are routes. You want three bindings, for two reasons the Slack page makes plain. From then on, the events you routed are delivered to the conversations you named, in the language and timezone set on each binding — and the ones you routed nowhere are delivered nowhere, which is why What goes out lists the types before you choose. Everything is configuration; there is no service of your own to run, no endpoint to publish, and no port to open — though there is one machine that does the sending, and which one is a key you set.
Nothing comes back, and that is the design
Notices are write-only. The chat app can post into one conversation and can read nothing — not that conversation, not any other. There is no button in the message that approves a gate, and there never will be one.
This is a property of the system, not a feature that is missing:
- A chat identity is not a fleet identity. The person behind a chat account is whoever your chat workspace says it is, on the strength of your chat vendor's session — not an actor the fleet has admitted, and not a hand at your workspace.
- A gate is a signed human act. It is recorded against a fleet actor, and the record of that act is what an auditor later reads.
- ⛔ An accept button in a chat client would therefore make the chat client a legislator of the fleet — it would let a decision enter the record on the authority of a session the fleet never issued and cannot examine.
So the notice carries the fact and the name of the thing it happened to; the act itself happens where acts happen. There is no link in the message and this section does not promise one — the reader takes the stream name to the console or the command line and decides there.
⚠ The same property is why replying to a notice does nothing, which surprises people the first time. See If you reply to the message.
What it costs to turn on
| Step | What you do |
|---|---|
| 1 | Create a chat app in your own workspace and grant it the scopes it needs — enough to post a message into a conversation, and nothing that reads one. |
| 2 | Put its token in an environment variable, or in a file, on the machine that will send. The binding holds the name of the variable or the path of the file; the token itself never goes into your configuration. |
| 3 | Find the conversation ids to deliver into. A channel is C… and a direct message is D…; both are accepted. ⛔ A user id beginning U… is refused when you set it, and the Slack page says why. |
| 4 | Set three bindings — for each one, where it delivers, which credential, which language, which timezone, and the two optional lines that appear under a notice. Three, for two reasons: the notice that reports a failed delivery must not travel through the binding that failed, and owner.act_owed — the type that asks a human for an act — belongs in that person's own conversation rather than a channel. |
| 5 | Set the four routes the Slack page copies out: owner.act_owed to the person's binding, gate.signed and merge.landed to the team's, and delivery.failed to the binding nothing else uses. ⚠ That is four routes, not a route for every type — What goes out lists more types than that block covers, and a type no route names is delivered nowhere. |
| 6 | Set notice.sender.primary to the operating system hostname of the machine that sends — what hostname prints on that host. ⛔ Not its registry machine id, which is what every other part of this site means by the name of a machine; this key is the one exception, and the two strings are the same only when hostname already prints the short form and nobody overrode the id — the Slack page works both ways they part. |
| 7 | Read the result back — saphan config show, or the configuration file itself. ⚠ What either prints for a notice.* key is not stated on this site; the Slack page says what that leaves you holding. |
These are keys in the operator's configuration file, written one at a time with
saphan config set — see Configuration for where that file lives and
how values are resolved. It lives on one machine, which is why step 6 exists and why
step 2 names a machine rather than a place.
What it costs afterwards is nothing you have to operate. Because the path is one-way, there is no callback address to keep reachable, no inbound port to expose, and no secret that your chat vendor has to hold on your behalf.
What is not here
⛔ These are named because a customer reading a promise is worse off than a customer reading a gap. None of the following is present:
| Not present | What that means for you |
|---|---|
| Retraction | A delivered notice is not withdrawn, edited or deleted by the product. What was posted stays posted. |
| Acknowledgement | Nobody can mark a notice as seen, and the fleet never learns whether one was read. Delivery is the only thing it knows about. |
| Silence windows | There are no quiet hours and no digest. A routed notice is delivered when the event happens. |
| Teams | Only the destination documented in this section is present. |
Where to go next
- Slack — the app, the destination rule, the bindings and routes to copy, which machine sends and where the token has to be, and what the delivery path refuses.
- What goes out — which notice types there are, which of them this site can describe, and the rule that the body of the work never travels.
- Languages and time — which languages you can select, how times are shown, and the one line you write yourself.
Running a metrics export
Three keys, the egress admission the address does not grant you, what each exit status means, and the one limit to read before you schedule anything.
Slack
The app and its two scopes, why the destination must be a conversation id, the three bindings and four routes to copy, which machine sends and where the token has to be, and what the delivery path refuses.