# Live calls

> Follow a call's transcript while it happens, and have the agent say something, take a note, or transfer the caller.

While a call is happening, your system can read what is being said, and ask the call to do three
things: say a sentence, take a note, or put the caller through to a person.

## Follow the transcript

```sh
node aigently.mjs follow 5f0c9a52-…
```

`GET /v1/conversations/{id}/live?after=0&wait=20` answers as soon as there is a line after `after`,
or after `wait` seconds with none. Each line has its `seq`, its `role` (`user` for the caller,
`assistant` for the agent), its `text` and when it was said. Send `next_after` back as `after` and
ask again, until `ended` is true: then the call is over and you have every line.

- It needs **Read transcripts** (`transcripts:read`), as reading the finished transcript does.
- Phone calls and browser calls have a live transcript. A chat does not: read its messages from its
  transcript.
- Lines are kept for a day. The conversation's transcript is the record after that.

## Ask the call to do something

Each request needs **Control live calls** (`calls:control`), a permission that is never part of a
starting point: it changes what a caller hears while they hear it. Each answers `202` at once with a
command. The call carries it out within a second or so, and
`GET /v1/conversations/{id}/commands/{command_id}` says how it went: `sent`, `taken`, then `done` or
`failed`.

- **Say** — `POST /v1/conversations/{id}/say` with `text`. The agent says it word for word, in its
  own voice, once it has finished what it is saying. It is in the transcript like anything else the
  agent says.
- **Note** — `POST /v1/conversations/{id}/notes` with `text`: something your system knows that the
  caller did not say, such as a payment that went through. The caller does not hear it. It reaches
  the agent as information, never as instructions, so it cannot change what the agent is for. With
  `respond: true`, the agent answers it at once; otherwise it uses it on its next turn.
- **Transfer** — `POST /v1/conversations/{id}/transfer` with `to_number`, or without it for the
  agent's own transfer number. The agent says its transfer line, the number rings, and the agent
  leaves once somebody answers, or tells the caller nobody could. The number is checked like any
  number an agent calls. A call is transferred once, and only a phone call can be.

A call takes these only once it has been answered and before it ends; otherwise the request is
refused with `conversation_not_answered` or `conversation_ended`. Every command is in the
[audit log](/guides/audit-log) under the key that sent it.

## With a test key

A test call is played rather than rung, and the same requests work on it: its lines appear in the
live transcript as its script plays, and a command is carried out at once. A sentence to say
appears as the agent's next line; nothing rings. See [Test mode](/guides/test-mode).