Asistent i glas

POST /v1/assistant · POST /v1/voice/speak · GET /v1/voice/confirmation · opseg public:read

AI asistent na sajtu razgovara sa posetiocem kao dobar agent: pita šta traži, predlaže 2–4 oglasa sa sajta, odgovara o njima, i (ako ključ ima public:inquiry) zakazuje pokazivanje ili šalje upit. Koristi isključivo oglase koje sajt vidi i ne izmišlja cene ni dostupnost.

Uslovi

Asistent i izgovor (/v1/assistant, /v1/voice/speak) rade samo kada plan agencije uključuje opciju „ai“ (inače 402 LICENCE). Svaka agencija ima mesečni limit AI-ja i glasa (429 AI_QUOTA / 429 VOICE_QUOTA). Limit poziva je 30 poruka asistentu u minuti po IP adresi.

Razgovor

API ne pamti razgovor: sajt šalje celu istoriju pri svakom pozivu (najviše 30 poruka; asistent koristi poslednjih 16).

POST /api/v1/assistant
x-api-key: pk_…
content-type: application/json

{
  "messages": [
    { "role": "user", "content": "Tražim dvosoban stan za kupovinu na Vračaru, do 200.000 €." }
  ],
  "language": "sr",
  "visitor": { "name": "Marko", "phone": "+381601234567", "email": null }
}

Polje	Pravilo
messages	1–30 poruka { role: "user" | "assistant", content }, content do 2.000 znakova
language	sr (podrazumevano) ili en: jezik odgovora
visitor	opciono { name, phone, email } (svako do 200/40/200 znakova ili null): ako ih već znate, asistent ih neće ponovo tražiti pre zakazivanja

Odgovor:

{
  "reply": "Imam dva stana koja odgovaraju: …",
  "speechToken": "Q2x1…",
  "actions": [
    {
      "name": "request_viewing",
      "result": { "requested": true, "id": "9d3c…", "property": "P-1042 · Trosoban stan, Vračar", "startsAt": "2026-11-03T09:00:00.000Z", "note": "Agencija će potvrditi termin." }
    }
  ]
}

Polje	Značenje
reply	tekst za prikaz posetiocu (običan tekst, može sadržati prelome reda)
speechToken	dozvola da se baš ovaj odgovor izgovori, vidi Glas
actions	radnje izvršene u ovom koraku: request_viewing (rezultat { requested: true, id, property, startsAt, note }) ili send_inquiry ({ sent: true, id }); neuspela radnja ima { error }

Dodajte odgovor u istoriju kao { role: "assistant", content: reply } i pošaljite sledeću poruku posetioca. Kada actions sadrži uspešan request_viewing, sajt može pustiti potvrdu glasom.

Linkovi u odgovorima

Kada asistent predlaže oglase, link do oglasa piše u obliku #/p/{slug} (format primera sajta apps/demo-site). Na svom sajtu te linkove prepišite u svoje adrese, npr. reply.replace(/#\/p\/([a-z0-9-]+)/g, "/nekretnine/$1").

Glas

Odgovor asistenta može da se izgovori glasom agencije (mp3). Da se plaćeni glas ne bi koristio za proizvoljan tekst, /v1/voice/speak izgovara samo tekst koji je napisao asistent: uz tekst se šalje speechToken iz istog odgovora, a token važi samo za tu agenciju i tačno taj tekst (prvih 600 znakova).

POST /api/v1/voice/speak
x-api-key: pk_…
content-type: application/json

{ "text": "Imam dva stana koja odgovaraju: …", "language": "sr", "token": "Q2x1…" }

• text: 1–600 znakova. Za duži odgovor pošaljite reply.slice(0, 600) sa istim tokenom.
• Odgovor je audio/mpeg, sa cache-control: public, max-age=86400. Isti tekst se ne naplaćuje dvaput.
• Tekst koji ne odgovara tokenu: 403 FORBIDDEN („Speech token does not match the text“).
• Glas nije podešen na serveru: 503 VOICE_DISABLED.

const r = await propertio.assistant.chat(history, { language: "sr" });
const mp3 = await propertio.voice.speak({ text: r.reply, token: r.speechToken, language: "sr" });
new Audio(URL.createObjectURL(mp3)).play();

Potvrda glasom

GET /api/v1/voice/confirmation?language=sr
x-api-key: pk_…

Vraća mp3 rečenice „Hvala vam! Vaš zahtev je primljen. Agent agencije {naziv} će vas uskoro kontaktirati.“ (language=en: „Thank you! Your request has been received. An agent from {name} will contact you shortly.“). Zgodno posle uspešnog upita ili zahteva za pokazivanje. Keširajte ga.

Govor posetioca (diktiranje)

API ne pretvara govor u tekst. Za unos glasom koristite Web Speech API u browseru (webkitSpeechRecognition / SpeechRecognition, lang = "sr-RS") i dobijeni tekst pošaljite kao poruku. Kada server ne može da izgovori odgovor (npr. 503), možete pasti na speechSynthesis u browseru.

Ključ u browseru

Asistent se obično poziva iz browsera, pa je ključ vidljiv. Tada:

• podesite dozvoljene sajtove;
• ili postavite mali proxy na svom serveru (/api/asistent → Propertio) koji dodaje ključ; tada limit od 30/min važi za IP vašeg servera, pa ga na proxyju ograničite po posetiocu.