# Asking people

> Ask a person a question, get their approval or send them a notice, then wait for the answer.

Some steps need a person: a manager approving a refund, a user picking a time, anyone confirming something an agent is about to do. `noclick.Human` reaches them with a page they answer on and an email, and gives you back an operation that finishes when they answer.

## Who you can reach

```python
import noclick

user = noclick.User.from_id("user_42")
user.human                               # the user, as a person to ask
noclick.Human()                          # the user you're acting for right now
noclick.Human.owner()                    # your account's owner
noclick.Human(email="finance@acme.com")  # anyone else
```

```ts
import { Human, User } from "noclick";

const user = User.fromId("user_42");
user.human;                                  // the user, as a person to ask
new Human();                                 // the user you're acting for right now
Human.owner();                               // your account's owner
new Human({ email: "finance@acme.com" });    // anyone else
```

Code acting for a user can reach only that user. `noclick.Human()` is the way to do it inside `as_user`, and the only way for a [session](https://www.noclick.com/docs/guide/sessions.md) or a key pinned to a user. `noclick.Human(email=...)` works from code that isn't acting for a user. `noclick.Human.owner()` always acts as your account, inside `as_user` too; a session or a key pinned to a user can't reach the owner (`noclick.PermissionDenied`).

## Ask a question

```python
request = user.human.ask(
    "Which time works for your cleaning?",
    options=["Thu 10:30", "Fri 14:00", "Neither"],
)
answer = request.wait()
print(answer.choice or answer.text)
```

```ts
const request = await user.human.ask("Which time works for your cleaning?", {
  options: ["Thu 10:30", "Fri 14:00", "Neither"],
});
const answer = await request.wait();
console.log(answer.choice ?? answer.text);
```

`wait()` returns an `noclick.Answer` with the option they picked (`choice`) and anything they wrote (`text`); the request's `answer`, as `HumanRequest.list` reads it and a `human.answered` [event](https://www.noclick.com/docs/guide/webhooks.md) carries it, is the same `{choice, text}` (an approval's is `{approved, text, note}`). Without `options`, they answer in their own words. A question takes up to 20 options.

## Ask for approval

```python
approved = noclick.Human(email="finance@acme.com").approve(
    "Refund $95.00 to Ana Lima?",
    details={"invoice": "INV-1042", "reason": "Charged for a cancelled visit"},
).wait()

if approved:
    issue_refund()
```

```ts
import { Human } from "noclick";

const approved = await (await new Human({ email: "finance@acme.com" }).approve("Refund $95.00 to Ana Lima?", {
  details: { invoice: "INV-1042", reason: "Charged for a cancelled visit" },
})).wait();

if (approved) {
  issueRefund();
}
```

An approval resolves to `True` or `False`. `details` is shown on the page, so put there whatever the person needs to decide. The person can add a note when they answer, and a decline usually carries one; `request.note` reads it.

An agent with [NoClick's own tools](https://www.noclick.com/docs/guide/agents.md#give-it-noclick-itself) asks this way too: a purchase, or a deletion that can't be undone (purging the [trash](https://www.noclick.com/docs/guide/undo.md), or deleting anything the trash doesn't keep), waits for your account's owner, on a page showing the exact price or what goes with it and which agent asked. A deletion to the trash happens at once, restorable for 30 days. The agent's turn waits on the answer, which arrives as the conversation's next turn.

## Send a notice

```python
user.human.notify("Your export is ready. It's in your dashboard.")
```

```ts
await user.human.notify("Your export is ready. It's in your dashboard.");
```

A notice needs no answer; its operation succeeds as soon as it's sent.

## Ask someone to connect an account

```python
calendar = noclick.Connection.from_name("calendar", integration="google_calendar", create_if_missing=True, user=user)
calendar = user.human.connect(calendar, reason="to book your appointments").wait()
```

```ts
import { Connection } from "noclick";

const calendar = Connection.fromName("calendar", { integration: "google_calendar", createIfMissing: true, user });
const connected = await (await user.human.connect(calendar, { reason: "to book your appointments" })).wait();
```

This emails a link for the [connection](https://www.noclick.com/docs/guide/connections.md) to that person and waits until they've connected it. `connect` also takes a connection's name, one of that user's connections. A user with no email address can't be sent one (`noclick.InvalidRequest`); make a connect link and pass it on yourself.

## How the request reaches them

Every request has a page where the person answers, `request.url`. It shows your [brand](https://www.noclick.com/docs/guide/brand.md). With the default `via="auto"`, NoClick emails the page to the person when it knows their email address:

```python
print(request.url)             # embed it, or send it yourself
print(request.delivered_via)   # ["web", "email"]
print(request.undelivered)     # channels that failed, each with a reason
```

```ts
console.log(request.url);            // embed it, or send it yourself
console.log(request.deliveredVia);   // ["web", "email"]
console.log(request.undelivered);    // channels that failed, each with a reason
```

`via=["web"]` sends nothing and leaves delivery to you, which suits people you reach through your own app or chat.

A request to your account's owner (`noclick.Human.owner()`) is the exception: NoClick sends them a link of their own, a key beside the request's id, and the id alone opens no page, so its `url` is null for your code. The owner answers from that link, or signed in; an agent holding the id can't answer from the page for them.

Your account's owner can also get a request as a text, from NoClick's own WhatsApp and iMessage numbers to the number they've verified with NoClick (by texting it, or under Settings → Phone). For the owner, `via="auto"` texts them on the app they last texted NoClick on, else emails them:

```python
noclick.Human.owner().notify("The new menu is live.")                    # on the app they text NoClick on
noclick.Human.owner().ask("Which logo?", options=["Round", "Square"], via=["whatsapp", "email"])
```

```ts
import { Human } from "noclick";

await Human.owner().notify("The new menu is live.");                    // on the app they text NoClick on
await Human.owner().ask("Which logo?", { options: ["Round", "Square"], via: ["whatsapp", "email"] });
```

A question's text carries its options and a link to its page. Texts cost nothing: they go out inside the conversation the owner's own last text opened, and WhatsApp refuses a text to an owner who hasn't written in the last 24 hours (it's listed in `undelivered`, and the email or page still reaches them). Only the owner gets texts: `"whatsapp"` or `"imessage"` for anyone else raises `noclick.NotAvailable`, so give your users a [number of your own](https://www.noclick.com/docs/guide/phone-numbers.md). `"sms"` and `"call"` raise `noclick.NotAvailable` for now.

## Waiting without blocking

A request is an [operation](https://www.noclick.com/docs/guide/operations.md), so it outlives your process. In a web server, store its id and pick it up later:

```python
request = user.human.approve("Publish the new pricing page?")
save(request.id)

# later, from anywhere
approved = noclick.Operation.from_id(saved_id).wait()
```

```ts
import { Operation } from "noclick";

const request = await user.human.approve("Publish the new pricing page?");
save(request.id);

// later, from anywhere
const approved = await Operation.fromId<boolean>(savedId).wait();
```

A request expires after 7 days unless you set `expires_in` (seconds or a `timedelta`, up to 30 days). Waiting on an expired request raises `noclick.Expired`.

## Answer from your own code

When the person who approves works in your own product, answer from there instead of the request's page:

```python
for request in noclick.HumanRequest.list(status="pending", kind="approve", answerable="code"):
    if request.request["details"].get("amount_usd", 0) < 50:
        request.approve(note="Under $50: fine.")
    else:
        request.decline(note="Refunds over $50 go through finance.")
```

```ts
import { HumanRequest, type JsonObject } from "noclick";

for (const request of await HumanRequest.list({ status: "pending", kind: "approve", answerable: "code" })) {
  const details = (request.request.details ?? {}) as JsonObject;
  if (Number(details.amount_usd ?? 0) < 50) {
    await request.approve({ note: "Under $50: fine." });
  } else {
    await request.decline({ note: "Refunds over $50 go through finance." });
  }
}
```

`approve` and `decline` answer as the person the request waits on: with a key acting for your account, an approval routed to your account (a held call on one of its connections, say); with a user's [session](https://www.noclick.com/docs/guide/sessions.md) or inside `as_user`, one addressed to that user. Anyone else gets `noclick.PermissionDenied`. So does a call NoClick holds for your account's owner (a purchase, a deletion that can't be undone, or a call your policy holds, made by an agent, a connected app or your app's code through NoClick), unless your key names the `approvals:answer` scope: your account's owner answers it from the link NoClick sends them (its `request["owner_only"]` is true, and its `url` is null), and your code with such a key, as [`noclick.Approval`](https://www.noclick.com/docs/guide/policy.md#answer-held-calls-from-your-code) does, never one made with that key. So does a question NoClick asks before granting an agent something on a person's say (to run app testing, to pay with a card above its approval threshold, to switch to a paid model): only the person it asks answers it, from the link NoClick sent them, or your account's owner signed in when it asks them; never your code, nor the agent that asked (its `url` is null too). NoClick's staff viewing your account answer none of its requests for your owner. `answerable="code"` lists only what your code can answer, leaving those out (a held call is listed for a key that names `approvals:answer`, unless that key made it or it asks terms a person accepts).

An answered approval of a held tool call does more than resolve the request: approved, NoClick runs exactly the call that was held (an operation's; a held shell command or other tool the agent makes again itself), and the agent gets a turn in the same conversation with its result; declined, the agent gets a turn with the decline and the note, so it can tell the person it's working for why. Either way its reply goes out wherever the conversation lives. A request a [policy rule](https://www.noclick.com/docs/guide/policy.md#rules-with-conditions) routes to a named approver is theirs alone to answer, through its link.

## Give an agent a person

A `Human` in an agent's `tools` lets the agent reach that person itself, and only that person:

```python
manager = noclick.Human(email="ops@acme.com", phone="+14155550123")
support = noclick.Agent.from_name(
    "support",
    create_if_missing=True,
    instructions="You answer billing questions. Ask the manager before refunding more than $200, "
    "and hand the conversation to them if the customer asks for a person.",
    tools=["stripe.create_refund", "search", manager],
)
```

```ts
import { Agent, Human } from "noclick";

const manager = new Human({ email: "ops@acme.com", phone: "+14155550123" });
const support = Agent.fromName("support", {
  createIfMissing: true,
  instructions: "You answer billing questions. Ask the manager before refunding more than $200, " +
    "and hand the conversation to them if the customer asks for a person.",
  tools: ["stripe.create_refund", "search", manager],
});
```

It gets three tools, each addressed to that person:

| Tool | What it does |
| --- | --- |
| `notify(message)` | Sends them a message (an email, with a page to read it on); the turn carries on. |
| `ask(question, options=None)` | Asks them. The turn waits, its operation `awaiting_human` (step `asking`), and their answer arrives as the conversation's next turn; the reply to that turn is the one `message()` returns. Meanwhile the conversation takes other messages. A question nobody answers in 7 days arrives as a turn saying so. One question per turn. |
| `hand_off(summary)` | Hands them the conversation: they get a page and an email with the agent's summary and the conversation so far, and the page shows the live transcript with a reply box. Their replies post into the conversation as `person` messages, which `history()`, `watch()` and your chat UI read like any other. The agent stays quiet until the conversation is handed back: a message to it joins the transcript (the person is emailed, at most every 15 minutes, that there's a new one), and a wake-up or event waits for the agent. On a phone call, it transfers the call to the person's `phone` (the user's, for a user) once the agent's reply is spoken. |

`manager.only("notify", "ask")` gives just some of them. Your [policy](https://www.noclick.com/docs/guide/policy.md) names them `human.notify`, `human.ask` and `human.hand_off`, so `require_approval=["human.hand_off"]` or `deny=["human.*"]` work as they do for any tool.

`noclick.Human()` in `tools` is the user each turn acts for (a thread with no user, your account's own, gets no tools from it), and `user.human` a particular user; `noclick.Human.owner()` is your account's owner, reached the way `via="auto"` reaches them, and a call is handed to their number (the agent their texts and calls reach, with [`answer_with`](https://www.noclick.com/docs/guide/humans.md#answer-the-owner-s-texts-and-calls-with-an-agent), is told who they are in that conversation: each turn there opens with a note naming them as your account has them, name, email and the number they text from, so it never asks; no other conversation is told); `noclick.Human(email=...)` is anyone else, and NoClick reaches them by email, so they need one (a `phone` is kept for a call's transfer). Only your account's agents may name the owner or anyone else. A person is reached as your account, or as the user when the person is one, and each message is capped and charged like any [request](https://www.noclick.com/docs/guide/humans.md#limits). Name a person once, with every tool they give; several people giving the same tool share one, which takes `person` to say whom.

A hand-off sends the `agent.conversation.handed_off` [event](https://www.noclick.com/docs/guide/webhooks.md#event-types), and the conversation's `status` is `handed_off` until it's handed back, from the person's page or from your code:

```python
support.hand_back("ticket-1841", user="user_42")
```

```ts
await support.handBack("ticket-1841", { user: "user_42" });
```

The agent answers again from the next message, which starts with what was said while the person had it and anything that woke it meanwhile. A hand-off nobody hands back returns to the agent after 30 days. A channel's conversation gets no person tools: the channel starts its turns.

A conversation that is an [email thread](https://www.noclick.com/docs/guide/inboxes.md#a-conversation-per-thread-answered-with-a-reply-tool) goes on by email: the person's replies are emailed to the thread's correspondent from the inbox's address, as the agent's own replies are (with their limits and charge), and the page tells them so. A reply that can't be sent, past the 48 hours replies are possible after the customer's latest message, say, isn't posted either, and the page says why.

## Answer the owner's texts and calls with an agent

What your account's owner texts NoClick's own WhatsApp and iMessage numbers, or says when they call NoClick's number, goes to NoClick's assistant: your account's agent `coordinator`, made the first time it's needed. Looking it up by name (`GET /v1/agents?name=coordinator`) with one of your account's own secret keys, sent without `NoClick-User`, makes it if the account doesn't have it yet, as its signed-in owner's lookup does; a key or session acting for one of your users, an MCP connection, an app's own code and an agent's turn only look. `answer_with` sends what the owner says to an agent of yours instead: a text's reply goes back on the app they texted on, and on a call the agent's reply is read aloud:

```python
owner = noclick.Human.owner()
assistant = noclick.Agent.from_name(
    "assistant", create_if_missing=True, instructions="You run the bakery's errands.", tools=["search", owner],
)
owner.answer_with(assistant)

assistant.message("What's on today?", conversation="owner")   # the thread their texts are in
```

```ts
import { Agent, Human } from "noclick";

const owner = Human.owner();
const assistant = Agent.fromName("assistant", {
  createIfMissing: true, instructions: "You run the bakery's errands.", tools: ["search", owner],
});
await owner.answerWith(assistant);

await assistant.message("What's on today?", { conversation: "owner" });   // the thread their texts are in
```

Each text, and each thing they say on a call, is a turn in the agent's conversation `"owner"`, so your code, the texts, the calls and anything else you point there share one thread. `conversation=` names another, a template over `{channel}` (`whatsapp`, `imessage` or `call`): `conversation="owner-{channel}"` keeps each app, and calls, their own. Give an [inbox](https://www.noclick.com/docs/guide/inboxes.md#a-conversation-per-thread-answered-with-a-reply-tool) and a [number](https://www.noclick.com/docs/guide/phone-numbers.md) the same conversation and the owner's email and calls to your numbers join it too.

Each turn opens with a short note saying how it came (a WhatsApp or iMessage text, or a phone call, with how to answer there), so the agent writes the way that app shows it; `![caption](url)` in a text's reply goes as media. The note reaches the model only: the conversation keeps what they said, as a `user` message whose `via` is `whatsapp`, `imessage` or `call`. The agent's own budget and policy govern its turns. A text's reply goes back when the agent's turn ends, however long it takes. Texts sent while the agent works on what they texted, or carries that job on by itself past a limit, join its turn: it reads them before its next step and answers them in its reply. Texts sent while any other turn runs there wait for it and go in its next turn together, in order. A [wake-up](https://www.noclick.com/docs/guide/agents.md#wake-it-up-later)'s turn in that conversation is said to them too: when what they last sent there was a text or a call, its reply is texted on the app they last texted on, unless the turn already told them (`notify` or `ask`), had nothing to say, or didn't go through. Each of these messages goes out once: one that can't be sent is tried again for a few minutes, then sent on their other app or by email, and it's in their web chat either way. A reply to their text always goes back on the app they texted from; a wake-up's reply or a `notify` isn't texted while they're watching the web chat, which shows it. A `notify` to them from another of the agent's conversations joins this one as the agent's message (`notification: true` in `history()`), so its next turn here knows what it said. A call's turn starts at once: while the conversation is still busy with a text, the caller hears that the agent is on it. A turn that can't start (a paused agent, spending that's paused) says why, on the app or aloud. `owner.answering()` is the agent answering now, and `owner.answer_with(None)` hands the owner back to NoClick's assistant. Your users don't reach NoClick's numbers: give them a [number of your own](https://www.noclick.com/docs/guide/phone-numbers.md) and its `answer_with`.

## Add an email to the owner

An account made by texting NoClick has no email. `add_email` sends a code to one, and `confirm_email` with the code makes it the owner's, to sign in with:

```python
owner = noclick.Human.owner()
owner.add_email("maya@morrowbakery.com")
confirmed = owner.confirm_email("482913")   # the code in that email
print(confirmed.email, "merged" if confirmed.merged else "added")
```

```ts
import { Human } from "noclick";

const owner = Human.owner();
await owner.addEmail("maya@morrowbakery.com");
const confirmed = await owner.confirmEmail("482913");   // the code in that email
console.log(confirmed.email, confirmed.merged ? "merged" : "added");
```

When an account already has that email, it takes this one in, everything it has with it (`merged`); whether one does is said only once the code matches. Only your account's own code, or an agent acting for it, adds the owner's email; an account that already has one gets `noclick.Conflict`. Called by an agent during its turn (its [`noclick` tool](https://www.noclick.com/docs/guide/agents.md#give-it-noclick-itself)), the email is `verified` and added once that turn ends. Codes last 15 minutes; an account gets three an hour, and five wrong codes end one.

## Limits

A message is at most 4,000 characters. Each account sends up to 500 request emails a day (then `noclick.RateLimited`), and each email is charged.

## Find requests

```python
noclick.HumanRequest.list(status="pending", kind="approve")
noclick.HumanRequest.summary(status="live")
```

```ts
import { HumanRequest } from "noclick";

await HumanRequest.list({ status: "pending", kind: "approve" });
await HumanRequest.summary({ status: "live" });
```

The console lists every request too, and lets you answer the ones addressed to you.
