Draft a reply for any conversation. The same drafts, articles and summary for a conversation that is **not** one of our sessions, a representative working in your own ticketing or helpdesk tool. Paste the conversation into turns and you get back what to say next, grounded in your knowledge base with citations.
Name an agent to borrow its knowledge collections, language and tone; without one the search covers everything you have published and the draft carries no brand voice. collections narrows the search further and never widens it.
Nothing is sent, and nothing is stored: this endpoint has no memory of the conversation you paste into it.
Draft a reply for a live session. Suggests what to say next in a chat session a representative is holding: reply **drafts** grounded in your knowledge base with citations, the **articles** behind them, and a **summary** of the conversation so far, the last one is what a representative who just claimed a waiting session needs first.
Nothing is sent. Read the draft, edit it, and send it yourself through POST /takeovers/{session_id}/reply with suggested_by_ai: true so the transcript records that a machine wrote it.
Send the conversation in turns as your console has it, a live chat's messages are realtime streams until the session ends, so the server cannot read them for you mid-conversation. Omit turns and the stored transcript is used instead, which is all a session that already ended has.
An empty sources array on a draft means the knowledge base had nothing for this question: show that to the representative rather than hiding it.
**Once a session is CLAIMED, this requires the X-Takeover-Claim header**, the claim_token from POST /takeovers/{session_id}/claim, for the same reason the live feed does: with turns omitted the draft is built from the stored conversation and the response echoes the customer's own message back in question, and claimed_by is visible to everyone who can list the queue. A session still WAITING in the queue needs no token: nobody holds it yet, so whoever is about to take it may prepare.
Parameters
Name
In
Type
Required
Description
session_id
path
string
Yes
The session id.
X-Takeover-Claim
header
string
The claim_token from this session's claim. Required once the session is claimed; omit it while the session is still waiting in the queue.
That session never requested a takeover (takeover_not_found).
409
You do not hold this session: it is claimed by someone else, or the X-Takeover-Claim token is missing or does not match (takeover_conflict). Deliberately indistinguishable, a refusal that told them apart would confirm whether a guessed rep_id is the real claimant.
422
No conversation was supplied and none is stored (no_conversation), or every turn belongs to the assistant or a representative (no_customer_turn).
4XX
Request error (validation, not-found, etc.).
502
The drafting model failed (assist_failed).
5XX
Server or upstream error.
Example request
curl -X POST "https://api.voiceland.ai/v1/takeovers/{session_id}/assist" \
-H "Authorization: Bearer VL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"max_articles": 5,
"rep_id": "maria@acme.example",
"turns": [
{
"role": "customer",
"text": "Does the premium plan cover a second address?"
}
]
}'
{
"articles": [
{
"chunk_id": "doc_plans#3",
"document_id": "doc_plans",
"score": 0.83,
"snippet": "The premium plan covers up to two addresses…",
"title": "Premium plan"
}
],
"drafts": [
{
"sources": [
{
"chunk_id": "doc_plans#3",
"document_id": "doc_plans",
"index": 1,
"title": "Premium plan",
"url": "https://example.com/plans"
}
],
"text": "Yes, the premium plan covers a second address at no extra cost [1]."
}
],
"grounded": true,
"question": "Does the premium plan cover a second address?",
"suggested_by_ai": true,
"summary": "The customer is on the premium plan and asks whether a second address is included."
}