Actions
Actions live on the agent’s Tools page, in a block called Your actions. The page holds four blocks: Built in (always on: search its knowledge, look up your lists, say it doesn’t know, and hand over where its kind does), Your actions (this page), Not for this agent (what its kind never has, each with the reason under its ?, such as Only a twin collects visitors’ details. This agent hands over instead.) and Integrations (Connect a tool).
Most of what an agent does is answer. An action is the narrow, declared way it can also do something: ask for a few specific details in the conversation, or make one request to a URL you choose.
Nothing runs until you add an action and switch it on, and nothing runs unless the sentence you wrote says it should.
One answer runs at most two actions, whichever kinds they are, and the same action can be one of the two. That’s a count, not a price: there’s no setting or tier that raises it.
The three kinds
Asks for a few specific things — an order number, an environment, a version — one at a time, in the visitor’s own words. At most six. What somebody doesn’t give is left blank, never guessed at.
POSTs a short summary to a URL you choose: a Slack incoming webhook, or your own endpoint. It goes to the address you give it and nowhere else.
Makes one request to an endpoint you name each time it runs, using a credential you stored. What the endpoint sends back is parsed to tell whether the call worked, and the names of the fields it contained are given to your agent as not read and not to be mentioned. An action added here reads no value back.
Kinds by agent
Nothing runs until you add one and switch it on. An agent with no actions is not holding anything back — it has simply never been told a tool exists.
Which of the three you can add depends on the kind of agent you are on:
| Agent | Collect details | Notify | Call your endpoint |
|---|---|---|---|
| Your own twin | Yes | Yes | Yes |
| Support Agent | No | Yes | Yes |
| Team Agent | No | Yes | Yes |
Note
Collect details is for your own twin. A Support Agent hands the conversation to a person instead, and that handover is where somebody leaves an address; a Team Agent doesn’t ask colleagues for theirs. On either, the kind isn’t offered on the form at all — the picker lists only what that agent can hold, so Add an action opens on Notify. (The door refuses it too, with the same sentence, so an older link or a direct API call gets the same answer.) Notify and Call your endpoint work on all three.
Start from a template
Add an action opens on Start from a template, or build your own. — three ready-made starting points beside Start from scratch: Stripe subscription status (look up a customer’s subscription status and plan by the address on their account), Order status (check an order’s status from your own order system), and CRM contact update (update a contact’s details in your CRM from the conversation). Picking one pre-fills the form below — the kind, the name, the fields it asks a visitor to attest — so you only fill in what’s actually yours: the endpoint URL, for the two that don’t call a service hiy already knows.
Stripe subscription status needs a Stripe connection first. Pick it with no Connections catalog entry for Stripe yet, and the picker says so with a link straight there instead of advancing; connect one and the template pre-fills the credential too, so there’s nothing left to paste there. It’s a starting point, not a finished call — you still set the endpoint and which response fields to read, the way Order status and CRM contact update already ask you to. Start from scratch skips all of this and opens the form empty, the way adding an action always worked.
Adding one
On the Tools page, Add an action — at the right of the Your actions heading — asks for four things: which kind, what to call it, when your agent should use it, and the one thing that kind cannot exist without — what to ask for, or where to send it.
It is created switched off, always. Arming it is a separate, deliberate act: switching on a Notify or a Call your endpoint asks you to confirm and says what will change, because those two leave the building. A Collect details action only ever writes inside hiy, so it switches on directly.
The confirmation is a panel over the page — docked above your thumb on a phone, centred on a wider screen. Nothing is armed until you press Switch it on. Not yet backs out, and so do Escape and a tap anywhere outside the panel; while it is open, the page behind it stays where you left it rather than scrolling under your finger.
A Call your endpoint is exactly what the form makes and nothing more. It POSTs to the URL you gave it, carrying three things: the action’s name, a short factual summary of what the visitor needs, and — on an agent that takes them — the facts your own site attested about the person asking, from that agent’s declared list and nothing outside it. A key you paste goes in the Authorization header as a bearer token.
hiy does parse the response, but only to work out whether the call succeeded and to name the fields it contained to your agent, with the instruction that they were not read and are not to be mentioned. An action added here declares no field to read back, so that instruction is the whole of what your agent ever learns from the body.
A declared field doesn’t have to sit at the top of the reply. If your endpoint nests the value you actually want — a result inside a list, a record inside another record — the field can point at exactly where it lives, up to a few steps deep. Your agent still only ever learns about the fields you named, never anything else the reply happened to contain.
A call can also take a short, specific value straight from what the visitor is saying — an order number, an account ID — and put it into the request you configured. It’s the same closed, careful approach Collect details already uses: your agent fills in only what you named, taken from the visitor’s own words, never invented and never free text.
The card is where you paste, replace and remove the key, and where you read what hiy has done with it. Nothing on the card sets which fields your agent reads back, which header the key goes in, or whether the request is a GET — an action added here is the POST described above, and that is all it is.
What your agent is told
The sentence under when to use it is not a note to yourself — it is what your agent reads to decide whether to run the action at all. Write it the way you’d tell a new colleague: “When someone asks about an order they’ve already placed.”
An action that’s switched off, or missing its credential, isn’t something your agent declines. It’s something your agent has never been told exists — because an agent that knows about a tool it cannot use will try it, get nothing, and then explain the nothing.
What a credential is, and what happens to it
A credential is a token or password your endpoint needs. You paste it once; hiy encrypts it and stores the encrypted value. No screen shows it back to you — only the last few characters, so you can tell two apart. That’s why the button says Replace and never Edit.
Every read is recorded: which action asked, and when. Open Connection, then What hiy did with it, on the action’s own card.
Removing is how a credential stops being usable. hiy revokes rather than deletes: the encrypted value is destroyed and the row describing it stays, so the record stays with it — added, replaced, read, refused, removed, each with a time. The action survives and still points at the same row; what changes is that it now refuses the call rather than making it without the key, says so on its card, and offers you a box for a new value.
Note
There is no reminder to rotate. hiy doesn’t warn you when a credential is old and doesn’t expire one for you. If your provider rotates on a schedule, that schedule is yours to keep — use Replace, and nothing else changes.
What your site can tell your agent
A Support Agent reached through a signed token can be told a few facts about the person asking, so an action needn’t ask a visitor for what your site already knows. You declare which facts on the agent’s Publish tab, under Install — up to six, by key names you choose; your server fills in the values when it mints a token. Neither party can act for the other: a host can’t invent a field you haven’t declared, and you can’t make a host send one it doesn’t have.
Those values reach an action and nothing else. They’re readable for the duration of one answer and are never written to the session row, the leads table, or anything joined to them — so there’s nothing to delete afterwards. A GET carries them on the query string and a POST nests them under attested. If one would overwrite a value your own address already sets, the call is refused rather than sent with hiy’s version on top, and your agent says so.
A Team Agent never receives them, whatever its token carries, and there’s no setting for that — nothing is built for an internal agent to read one.
The visitor is told which keys arrived — the names, never the values — on the answer itself. A key name is a word a stranger reads, so choose it accordingly.
Open on your site
A Support Agent open on your websites answers visitors your server never vouched for — anyone with a script can be one. For them, per answer, only a look-up that needs no key runs:
| Action | For an open visitor |
|---|---|
Look something up (GET) with no stored key, on an agent with no site facts | Runs as usual |
| Call your endpoint with a stored key | Off — your key would answer for anyone |
Send data to your endpoint (POST) | Off — it would write into your systems on a stranger’s say-so |
| Notify | Off — it would post whatever a stranger asks into your own channel |
| Any call, on an agent that declares site facts | Off — the call would go out without the facts that scope it |
It is decided at answer time, so an action you add later is covered too, and the dialog that opens the agent names the actions that keep running. A visitor carrying your own server’s token gets every action, exactly as before.
Previews rehearse writes
When you try an action from Test, or from your own preview of your live agent, it doesn’t really run. For a call that leaves the building, hiy shows you the exact request that would have gone out; for a Collect details action, your agent says what it would have recorded instead of recording it. Nothing is sent and nothing is created.
Attested facts are rehearsed too, with a stand-in where each declared value would go: a preview has no visitor and therefore no token to read one from, so a stand-in shows you the shape of the request without inventing a fact about somebody who isn’t there.
This is the one deliberate difference from the rest of the preview, which is otherwise identical to what a visitor gets — because a real ticket in your real system, created by you testing, is worse than not being able to test the last step. The only unrehearsed run happens on a real visitor’s conversation.
What a visitor sees
An answer that leaned on an action that left the building — a Notify, or a Call your endpoint — carries a short line saying which action ran and how it went. Never the request, the endpoint, or an id from your systems: only the name you gave the action, and the outcome.
For those two the line is always shown. Hiding your sources is your right; hiding that an answer left the building is not. A Collect details action carries no such line — the same rule, not an exception: nothing left the building, and the person who typed the details watched themselves type them.
Who processes what
The system your action writes into is your processor, chosen by you under your own agreement with them. hiy doesn’t select it, contract with it, or process what it holds on its own behalf: hiy makes the call your action describes and records that it happened. It isn’t added to hiy’s own list of subprocessors.
A fact your site attested about the person asking is your data about your own user, and the same answer follows: you are its controller, hiy never asks for it and never keeps it, and it exists here only for as long as the answer it was sent for.