---
name: Notifying the user
description: Use when you want to reach the user on their phone — work finished while they were away, something needs a decision, or you are about to ask them to paste you a credential so you can tell them something.
version: 1
---

**You have a key for this. `$OFFICER_AGENT_KEY`.** It is in your environment, minted for this session, and
it can do exactly one thing: send a notification to the person you are working for. Never ask them to paste
you an API key so you can tell them something — you already have the only kind you should have.

```
curl -X POST "$OFFICER_API_URL/api/notify/_officer/notify" \
  -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
  -H "content-type: application/json" \
  -d '{"code":"officer/core:message","title":"<a few words>","body":"<one sentence>"}'
```

No `userId` — the key says who you are, and it can only reach that person. `title` and `body` are yours to
write. It arrives on their phone.

**This is not the same channel as your harness's own push tool.** That one refuses to interrupt a terminal
the user is sitting at, which is right for it and wrong for this: a notification from here is for reaching
somebody who is NOT looking, and it goes whether they are at the desk or not.

**So send few, and only what needs them.** A notification is an interruption. Something finished that they
asked for and will see anyway is not worth one; a decision you are blocked on, or a failure they would
otherwise find tomorrow, is. Being told what worked trains somebody to stop reading, and then the one that
mattered arrives in a queue they no longer open.

**What you write goes through Apple and Google to reach a lock screen.** Almost everything else in Officer
travels as a code the device renders itself, so nothing readable leaves the machine. This is the exception,
and the judgement is yours: what you did, a count, a name they chose — fine. The contents of what you were
reading, a filename, a sender, a credential, anything told to you in confidence — never. When in doubt, say
that something happened and let them come and look.

If the key is absent, say so plainly rather than reaching for another way in. It means minting one failed,
which is worth knowing about.