text

Start a conversation with an agent and get its greeting. Use once, before send_message, to begin a new text conversation.

The returned interaction_id is the handle for everything that follows and is the id of the record in the log — one id, because a conversation and the record of it are the same conversation.

By default the conversation runs against the agent's published version, and an agent that has never been published is refused (409). To test a draft before publishing it, pass draft_version_id — the agent's draft, as get_draft returns it. The conversation then runs against the draft as it stands at this call, is metered like any other, and its record carries draft_test: true, which analytics leave out by default. An edit to the draft afterwards is not seen by this conversation: open a new test after each change. A draft_version_id that is not that agent's draft is refused (409). Only this operation can open a conversation against a draft; no channel or line can.

context says who the conversation is with, and is accepted only from an organization API key, called from your server: the same request with a signed-in session is refused (403).

End the conversation. Use when the conversation is over and should stop taking turns; the agent says its own farewell and the record is finished, and the id stops working afterwards.

Answer a question the agent asked, and watch it finish what it started. Use only in response to a confirmation request the agent raised mid-turn.

An action with a consequence outside a draft is put to you as a question and happens on your yes. This is the yes — or the no — and the reply is the rest of the turn the question interrupted, streamed exactly like a message: one frame per event as it is recorded, ending in end or error.

On confirmed the tool runs with the arguments the request showed you, and the agent answers with what it returned. On declined nothing runs, no tool call appears in the record, and the agent answers anyway — you are told what was not done rather than left with a stream that goes quiet.

A question can only be answered once. A second answer to the same request is a 404, whichever way it was answered the first time, because the answer that won is already in the trace.

A signed link, good for 15 minutes, to a file sent on this conversation with a message, with its name, type and size. Use when a line of the conversation names a file (its ref_id) and you need the file itself; ask again for a fresh link once one expires. view=inline asks for a link that opens the file in place rather than saving it -- honoured for a JPEG, PNG, GIF or WebP image and a PDF; any other file is still a download. Works while the conversation is open and after it ends, for as long as retention keeps the file. Changes nothing. Answers 404 for a conversation you may not read, and for a file that is not kept (never kept, refused, or purged).

Say something, and watch the agent answer. Use for every turn of an already-open conversation, after open_conversation.

Each event of the turn is framed the moment it has been recorded, so what arrives here is the trace being written rather than a report of it. Three things follow and all three are deliberate. An unknown or finished conversation is a plain 404, decided before the stream exists, rather than an error frame inside a response that already claimed to be a success. Disconnecting stops the reading and nothing else — the turn finishes and the record is complete, so reconnecting and sending again continues the same conversation. And a client that stops reading without disconnecting is dropped rather than allowed to hold up the recording; service.STREAM_BUFFER argues which side gives way.

The request's own session is not involved: a turn outlives the response that started it, so it opens one of its own.

A message may carry up to five attachments -- images or documents, base64, at most 8 MiB together -- with or without text; attachment is the one-file spelling, and a message sends one or the other. The agent reads each where its profile names a reader and its switches take the kind, as a description or as the document's contents, marked as such and in the order sent; a video, or a kind it does not take, is announced to it. Each file is kept for your retention window and purged with the conversation. Audio is refused (422) on this channel for now.

Tell this conversation to stop asking, or to start asking again. Use when the caller wants consequential actions to run without a confirmation request, or wants to turn that confirmation back on.

auto proceeds without the question from here on; ask is the default and puts every consequential action to you. It belongs to this conversation and to nothing else — not to you, not to your organization — so the next one you open starts by asking again unless you say otherwise.

The switch is recorded whichever way it goes. Turning the questions off turns off the asking and never the recording, and the record is where you find out what was done.

A question already on your screen stays there: this changes what happens to the next action, and does not answer the one you are looking at.