Integracije

Vgraditev widgeta

Vgradite widget za spletni klepet HelpStack na katero koli spletno stran z eno samo oznako script.

Hitre dejstvice#


Nalagalnik	`https://helpstack.eu/widget.js`
Avtentikacija	Ni — končne točke widgeta so javne
Transport	Socket.IO (primarni) + HTTP rezerva
Vrsta kanala	`WEBSITE_CHAT`
Omejitev hitrosti	~30 zahtev/min/IP za config/FAQ/status; ~20 sporočil/min/obiskovalec za HTTP rezervo sporočil
Nadzor izvora	Neobvezni seznam dovoljenih domen po kanalu (403, če ni dovoljen)

Nalagalnik izpelje svojo lastnost baseUrl iz izvora lastne oznake <script src>, zato widget.js, ki ga streže helpstack.eu, samodejno komunicira s HelpStack — ni treba konfigurirati ničesar drugega.

Odrezek za vgraditev#

<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>

CHANNEL_ID je id vašega kanala WEBSITE_CHAT. Nalagalnik se samodejno inicializira iz parametra poizvedbe ?id= — dodatnega JavaScripta ni potrebno.

Kje dobiti CHANNEL_ID#

Na nadzorni plošči pojdite na Nastavitve → Kanali, odprite (ali ustvarite) kanal Spletni klepet in kopirajte njegov id z gumbom za kopiranje poleg kanala. Ta id posredujete kot ?id=CHANNEL_ID.

Kako deluje nalagalnik#

Skripta prebere svojo lastno <script src>, da ugotovi:
- baseUrl — izvor skripte (npr. https://helpstack.eu)
- channelId — parameter poizvedbe ?id=
Vstavi lebdeči mehurček klepeta in <iframe>, ki kaže na:
```
{baseUrl}/widget/{channelId}?visitorId={visitorId}
```
Iframe odpre povezavo Socket.IO za sporočanje v realnem času, z HTTP rezervo, ko WebSocket ni na voljo.

Identiteta obiskovalca#

Nalagalnik ustvari trajni id obiskovalca, shranjen v localStorage:

Ključ	Oblika vrednosti
`chat_widget_visitor_id`	`visitor_<uuid>`

Isti visitorId se znova uporablja pri nalaganju strani in sejah v tem brskalniku, zato se vračajoči obiskovalec znova poveže s svojim obstoječim pogovorom. Brisanje localStorage (ali drug brskalnik/naprava) ustvari novega obiskovalca in novo nit pogovora.

Programski API#

Nalagalnik izpostavi globalni objekt window.ChatWidget:

window.ChatWidget.init('CHANNEL_ID'); // ročna inicializacija (če ne uporabljate ?id=)
window.ChatWidget.open();             // odpre ploščo klepeta
window.ChatWidget.close();            // zapre ploščo klepeta
window.ChatWidget.toggle();           // preklopi med odprtim/zaprtim

Na voljo je tudi pomočnik s čakalno vrsto ukazov za odloženo obliko, ki se uporablja v komentarju odrezka:

window.chat('init', 'CHANNEL_ID');

Ni API-ja za registracijo orodij na strani odjemalca. Nalagalnik ne izpostavi nobenega registerTool() ali upravljalnika orodij na strani odjemalca. Orodja agenta na strani odjemalca so posredovana s strežnika prek vtičnice iframe (glejte Orodja agenta po meri), ne pa registrirana iz JavaScripta vaše strani.

Konfiguracija videza#

Videz je konfiguriran na nadzorni plošči, ne prek odrezka za vgraditev. Widget ga pridobi s strežnika (GET /api/widget/[channelId]/config) in ga uporabi prek spremenljivk CSS. Preverjene nastavljive možnosti:

Polje	Opombe
`primaryColor`	Barva v šestnajstiškem zapisu. Privzeto `#3b82f6`
`position`	`bottom-right` \| `bottom-left` \| `top-right` \| `top-left`
`mobilePosition`	Isti nabor vrednosti kot `position`, uporabljen na mobilnih zaslonih
`bubbleIconType`	`custom` ali prednastavitev
`bubbleIconName`	Ena od: `message`, `help`, `smile`, `headphone`, `zap`, `heart`
`bubbleOffsetX`	Vodoravni odmik mehurčka
`bubbleOffsetY`	Navpični odmik mehurčka
`greetingMessage`	Pozdravno besedilo, prikazano ko se plošča odpre
`avatarUrl`	Avatar agenta/blagovne znamke
`showOnlineStatus`	Ali prikazati stanje na spletu/izven spleta
`offlineMessage`	Sporočilo, prikazano ko je kanal izven spleta

Javne končne točke widgeta#

Vse končne točke so javne (brez avtentikacije) in omejene po hitrosti glede na IP/obiskovalca.

Metoda	Pot	Namen
`GET`	`/api/widget/[channelId]/config`	Konfiguracija widgeta (barve, položaj, pozdrav, avatar, status). ~30 zahtev/min/IP
`GET`	`/api/widget/[channelId]/faqs`	Do 5 žetonov s pogostimi vprašanji za pozdrav. ~30 zahtev/min/IP
`GET`	`/api/widget/[channelId]/status`	Ali je kanal trenutno v spletu
`POST`	`/api/widget/[channelId]/upload`	Nalaganje datoteke `multipart/form-data`
`POST`	`/api/widget/message`	HTTP rezerva za pošiljanje sporočila, ko WebSocket ni na voljo. ~20 sporočil/min/obiskovalec

Odgovor pri nalaganju (POST /api/widget/[channelId]/upload):

{
  "storagePath": "...",
  "publicUrl": "...",
  "fileName": "...",
  "fileSize": 12345,
  "contentType": "image/png",
  "width": 800,
  "height": 600
}

width in height sta prisotna samo za slike.

Rezerva za sporočila (POST /api/widget/message) — telo zahteve:

{
  "channelId": "CHANNEL_ID",
  "visitorId": "visitor_<uuid>",
  "content": "Hello, I need help",
  "visitorInfo": {
    "userAgent": "...",
    "currentUrl": "https://example.com/pricing",
    "referrer": "https://google.com"
  }
}

visitorInfo je neobvezen. Kanal mora biti vrste WEBSITE_CHAT, sicer je zahteva zavrnjena. Ob uspehu ovojnica odgovora v polju data vsebuje { messageId, conversationId, createdAt }.

Dogodki v realnem času (Socket.IO)#

Iframe komunicira s strežnikom prek Socket.IO.

Widget → strežnik

Dogodek	Koristna obremenitev
`join`	`channelId`, `visitorId`, `visitorInfo { userAgent, currentUrl, referrer }`
`message`	Odhodno sporočilo obiskovalca
`typing`	Indikator tipkanja obiskovalca
`heartbeat`	Ohranjevalnik prisotnosti
`tool:result`	Rezultat izvajanja orodja na strani odjemalca
`tool:error`	Napaka pri izvajanju orodja na strani odjemalca

Strežnik → widget

Dogodek	Koristna obremenitev
`joined`	Začetna sporočila in konfiguracija widgeta
`message`	Novo sporočilo agenta
`agent_typing`	Indikator tipkanja agenta
`tool:execute`	Zahteva za zagon orodja na strani odjemalca v brskalniku

Seznam dovoljenih domen#

Kanal lahko omeji, kateri izvori smejo naložiti widget. Ko je seznam dovoljen konfiguriran in zahtevani izvor ni na njem, strežnik odgovori s 403. Konfigurirajte seznam dovoljenih v nastavitvah kanala na nadzorni plošči. Pustite prazno, da dovolite kateri koli izvor.

Primer minimalne strani#

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>HelpStack Widget Demo</title>
  </head>
  <body>
    <h1>My website</h1>
    <button onclick="window.ChatWidget.open()">Need help?</button>

    <!-- HelpStack widget -->
    <script
      src="https://helpstack.eu/widget.js?id=CHANNEL_ID"
      async
    ></script>
  </body>
</html>

Sorodne teme#

Uredi to stran na GitHub