Agent assist

Die Beschreibungen der Endpoints und der Felder erscheinen auf Englisch, genau so, wie die API sie ausliefert. Das ist Absicht: Sie lesen hier, was Sie auch in den Antworten sehen.

POST /v1/assist/suggest#

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.

Anfragetext

application/json Schema: AssistSuggestRequest

Antworten

Beispielanfrage

curl -X POST "https://api.voiceland.ai/v1/assist/suggest" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": "front-desk",
  "lang": "el",
  "turns": [
    {
      "role": "customer",
      "text": "Πόσο κοστίζει το premium;"
    },
    {
      "role": "human_agent",
      "text": "Ένα λεπτό να το δω."
    }
  ]
}'

Eine erfolgreiche Antwort liefert ein AssistResponse.

Beispielantwort

{
  "articles": [],
  "drafts": [
    {
      "sources": [
        {
          "chunk_id": "doc_plans#1",
          "document_id": "doc_plans",
          "index": 1,
          "title": "Τιμοκατάλογος"
        }
      ],
      "text": "Το premium κοστίζει 10 ευρώ τον μήνα [1]."
    }
  ],
  "grounded": true,
  "question": "Πόσο κοστίζει το premium;",
  "suggested_by_ai": true,
  "summary": "Ο πελάτης ρωτά την τιμή του premium."
}

POST /v1/takeovers/{session_id}/assist#

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.

Parameter

Anfragetext

application/json Schema: AssistSessionRequest

Antworten

Beispielanfrage

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?"
    }
  ]
}'

Eine erfolgreiche Antwort liefert ein AssistResponse.

Beispielantwort

{
  "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."
}

Schemata#

AssistArticle#

AssistDraft#

AssistResponse#

AssistSessionRequest#

AssistSource#

AssistSuggestRequest#

AssistTurn#

Error#

Error envelope returned for non-2xx responses.