Live calls

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

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 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.