Transport: WebSocket, HTTP-reserv och återanslutning

Den här sidan beskriver vad som händer mellan widgeten i webbläsaren och chattservern. Du behöver den för felsökning (nätverksfliken i utvecklarverktygen), proxy- och brandväggsregler samt din Content Security Policy.

Viktigt: överföringsprotokollet är gränssnittet mellan vår widget och vår server. Egna klienter som talar protokollet direkt stöds inte officiellt; fält kan utökas inom protokollversion 1. För egna gränssnitt använder du JavaScript-API:et, för serverkopplingar webhooks och server-API:et.

Adresser

• WebSocket: wss://ws.reactive.chat/rc_wss/
• HTTP-reserv, offlineformulär, uppladdningar: samma adress med https://, alltså https://ws.reactive.chat/rc_wss/h/…, https://ws.reactive.chat/api/offline/<SITE_KEY> och https://ws.reactive.chat/rc_wss/upload/…
• Widgetfiler: https://cdn.reactive.chat/

Hur widgeten hittar WebSocket-adressen:

1. data-rc-ws-url på laddartaggen, window.ReactiveChatSettings.wsUrl eller ReactiveChat('boot', { wsUrl }) – om det är angivet gäller det värdet.
2. Annars härleds den från platsen för loader.js: wss://ws. + domänens sista två delar + /rc_wss/. cdn.reactive.chat blir wss://ws.reactive.chat/rc_wss/.

Det ger två fallgropar:

• Om du distribuerar loader.js från egen domän härleder widgeten en adress under din domän. Ange då data-rc-ws-url (se Snabbstart).
• Med tvådelade ändelser som .co.uk blir härledningen fel. Ange data-rc-ws-url uttryckligen.

WebSocket-vägen utvärderar inga frågeparametrar.

Upprätta anslutningen

• Tidpunkt: widgeten ansluter inte medan sidan laddas utan vid den första riktiga interaktionen (musrörelse, klick, tangenttryckning, mushjul, pekning, fokus). Den ansluter direkt om chattfönstret är öppet eller öppnas, en konversation för besökaren är känd eller oskickade meddelanden väntar. Med data-rc-connect="load" på valfritt element (vanligtvis laddartaggen) eller window.ReactiveChatSettings.connect = 'load' ansluter den vid laddningen som tidigare. Regler som utlöses en viss tid efter sidvisningen räknar från den första interaktionen.
• Underprotokoll: widgeten öppnar new WebSocket(url, 'rc.v1') och servern speglar rc.v1. Protokollversionen finns inte i adressen utan i varje ram (v: 1).
• Bara textramar, i UTF-8; en ram = ett meddelande. Ingen komprimering (permessage-deflate är avstängt på serversidan).
• Handskakning: efter open skickar widgeten init inom högst 5 sekunder; servern svarar med init_ok. Om open inte kommer inom 8 sekunder räknas försöket som misslyckat; om init_ok inte kommer inom 10 sekunder återansluter widgeten.
• Ursprungskontroll: servern jämför värdnamnet i Origin-huvudet med projektets domäner (Tillåtna ursprung i kontot). Protokoll och port räknas inte; underdomäner matchar (www.your-company.com matchar your-company.com, notyour-company.com gör det inte). Vid fel: origin_denied, sedan stängningskod 1008, inget nytt försök. Om ingen domän är angiven i projektet görs ingen ursprungskontroll – ange därför alltid dina domäner.

Ramformat

Varje meddelande i båda riktningarna har den här formen:

{ "v": 1, "t": "msg", "id": "01JAB3C4D5E6F7G8H9JKMNPQRS", "ts": 1792500000000, "d": { } }

• v (heltal, obligatoriskt) – protokollversion, för närvarande 1.
• t (sträng, obligatorisk) – meddelandetyp, [a-z0-9_]{1,24}.
• id (sträng, obligatorisk) – ULID: 26 tecken i Crockford Base32, bara versaler. Det är också nyckeln för deduplicering.
• ts (heltal, obligatoriskt) – millisekunder sedan 1970, bara för diagnostik.
• d (objekt, obligatoriskt) – data, aldrig null, {} om tomt.

Okända typer och fält ignoreras utan felmeddelande – det gör äldre widgetar kompatibla med nyare servrar.

Meddelandetyper i överblick

Från widgeten till servern:

• init – registrering av anslutningen: webbplatsnyckel, sessions-, besökar-, flik- och konversations-ID, språk, samtyckesstatus, eventuell signerad identitet (user), sidkontext (ctx) och återupptagningspunkt (resume).
• msg – ett besökarmeddelande (text, upp till 5 bilagor, svar på snabbsvar eller formulär).
• typing – skrivindikator (start/stop). Inmatningsfältets innehåll skickas aldrig.
• read – läst till och med seq.
• ctx – ändrad kontext, till exempel vid navigering i en SPA eller efter identify.
• csat – omdöme (tummen upp/ned, kommentar upp till 1 000 tecken).
• upload_req – begäran om uppladdningsgodkännande (namn, MIME-typ, storlek, SHA-256).
• transcript, forget, consent – konversation via e-post, radera egna uppgifter, ge/återkalla samtycke.
• ping – håll anslutningen vid liv.

Från servern till widgeten:

• init_ok – bekräftade ID:n, historik, utseende, funktioner och gränser (se nedan), resultat från identitetskontrollen (identity.verified).
• msg – meddelanden (inklusive ekot av besökarens eget meddelande med client_id).
• bot_typing, bot_stream – AI-assistenten tänker eller skriver; bot_stream skickar alltid hela den text som är synlig hittills, högst var 150:e ms.
• typing, read, handoff, queue_pos, proactive, conv_list, error, pong.

Felkoder

Ett fel kommer som en ram t: "error" med d.code, d.message (engelska, bara för utvecklare), d.retry (no, immediate, backoff, after_reinit) och vid behov d.retry_after_ms och d.detail. Listan är sluten; en okänd kod behandlas som internal.

• bad_json – ogiltig JSON; efter tre förekomster stängningskod 1008.
• bad_envelope – ramen bryter mot formatet (även: ULID avviker mer än 24 h, detail.reason: stale_or_future).
• unsupported_version – versionen kan inte förhandlas; stängningskod 4001.
• unknown_site_key – webbplatsnyckeln är okänd, projektet pausat eller arkiverat; stängningskod 4002.
• origin_denied – ursprunget finns inte bland projektets domäner; stängningskod 1008.
• visitor_blocked – besökaren blockerad; stängningskod 1008.
• auth_failed – identitetskontrollen misslyckades, detail.reason: no_hash, bad_hash, bad_exp, expired, exp_too_far. Sessionen fortsätter anonymt.
• not_initialized / already_initialized – meddelande före init, eller ett andra init.
• init_timeout – inget init inom 5 s; stängningskod 4004.
• conversation_not_found / conversation_closed
• rate_limited – anropsgräns; med retry_after_ms. Om det upprepas på samma anslutning stänger servern med 4008.
• payload_too_large – ram över 64 KiB.
• msg_too_long – text längre än planens gräns, detail.max.
• unsupported_kind, attachment_invalid
• upload_disabled, upload_too_large, upload_mime_denied, upload_expired
• consent_required – åtgärden kräver samtycke.
• dnd_active – ”Stör ej” är aktivt.
• session_conflict – för många anslutningar i samma session (fler än 3); stängningskod 4003, fliken blir en följare.
• internal, unavailable – tillfälligt; nytt försök efter en väntetid.

Stängningskoder

• 1000, 1001, 1006, 1011, 1013, 4004 – widgeten återansluter (efter en väntetid).
• 1008 – ursprung avvisat, upprepat ogiltig JSON, blockering genom skyddet mot missbruk. Inget nytt försök på den här sidan.
• 4001 – versionen kan inte förhandlas. Inget nytt försök.
• 4002 – webbplatsnyckeln okänd eller projektet inaktivt. Inget nytt försök.
• 4008 – upprepad anropsbegränsning. Widgeten väntar retry_after_ms och återansluter.
• 4003 – sessionskonflikt; fliken körs som följare till en annan flik.

Gränser per anslutning

Servern skickar de bindande värdena i init_ok.limits och init_ok.features:

• heartbeat_ms 25 000 – widgeten skickar ping 25 s efter senaste utgående meddelande.
• pong_timeout_ms 10 000 – två uteblivna pong leder till återanslutning.
• idle_timeout_ms 70 000 – servern stänger efter 70 s utan inkommande ram (1001).
• max_frame_bytes 65 536 – större ramar: payload_too_large.
• msg_per_10s 20 och frames_per_10s 120 – token bucket per anslutning; över detta rate_limited.
• reconnect_cap_ms 30 000 – längsta väntetid mellan nya försök.
• dedup_window_ms 86 400 000 – 24 timmars deduplicering.
• features.max_msg_len – tecken (Unicode-kodpunkter) per besökarmeddelande: 1 000 i Free-planen, 4 000 i betalplaner. Widgeten skickar inte för långa texter.
• features.max_upload_bytes, features.allowed_mime – se Gränser och kvoter.

Återanslutning, ordning och dubbletter

• Väntetid: min(30000, 500 × 2^(attempt−1)) ms, där ett slumpvärde i den övre halvan används (försök 1: 250–500 ms, från försök 7: 15–30 s). Tre gånger så lång i bakgrundsflikar. Ett retry_after_ms från servern är den nedre gränsen. Antalet försök är obegränsat; räknaren återställs bara vid init_ok. Om webbläsaren rapporterar online försöker widgeten direkt; om den är offline väntar den.
• Ordning: varje meddelande i en konversation har ett luckfritt seq som börjar på 1. Meddelanden visas efter seq, inte efter tid. Vid återanslutning skickar widgeten resume.last_seq och upp till 50 väntande ID:n; servern levererar allt därefter (högst 100 meddelanden, annars has_more) och upprepar bekräftelser för meddelanden som redan kommit fram.
• Inga dubbletter: servern kommer ihåg varje meddelandes id i 24 timmar. Ett upprepat meddelande sparas inte igen men får samma bekräftelse. ”Skicka igen” i widgeten använder samma id.
• Tillstånd för ett utgående meddelande: pending → sent → delivered (eko från servern) → read; failed efter 5 försök, efter 24 h eller vid retry: "no".
• Offlinebuffert: om anslutningen bryts läggs meddelanden i en buffert (högst 50 poster, 128 KiB, 24 h) – med samtycke i localStorage, utan det i sessionStorage – och skickas vid nästa init_ok.
• Flera flikar, en anslutning: webbplatsens flikar väljer en ledare (Web Locks, annars en livssignal i localStorage); bara ledaren håller anslutningen, och övriga kommunicerar via BroadcastChannel.

HTTP-reserv

Om ett nätverk inte släpper igenom WebSocket fortsätter chatten via vanliga HTTPS-anrop – med samma ramar och gränser. Bara widgeten använder detta; agentgränssnittet ansluter alltid via WebSocket. Den korta versionen för redaktörer finns under HTTP-reserv.

När den används:

• webbläsaren stöder inte WebSocket;
• två WebSocket-försök misslyckas i följd innan en WebSocket någonsin upprättats på den här sidan (ett försök utan resultat efter 8 sekunder räknas som misslyckat);
• sessionStorage innehåller posten rc_http som är mindre än 30 minuter gammal (följande sidor i samma flik);
• du tvingar fram det med data-rc-transport="http" (på valfritt element som finns i dokumentet vid starten) eller med window.ReactiveChatSettings = { transport: 'http' } före laddaren. ReactiveChat('boot', { transport: 'http' }) har ingen effekt – anslutningstypen bestäms vid starten.

Utan fetch i webbläsaren finns ingen reserv. Om en befintlig WebSocket-anslutning bryts återansluter widgeten via WebSocket. Efter byte till reserven kontrollerar den diskret en gång per sida om WebSocket nu kommer igenom; om så är fallet raderar den rc_http och nästa sida använder WebSocket igen.

Anropen (under https://ws.reactive.chat/rc_wss/h/):

• POST h/auf – öppnar anslutningen. Svar {"v":1,"cid":"…","tok":"…","poll_ms":25000,"idle_ms":60000}. tok är en kortlivad anslutningstoken (32 tecken).
• GET h/<cid>/sse?tok=… – Server-Sent Events, id: och data: per ram, en livssignal var 15:e s. Missade ramar levereras via Last-Event-ID.
• GET h/<cid>/poll?tok=…&nach=<n> – långpollning; servern håller anropet öppet i upp till 25 s och svarar med {"v":1,"n":…,"rahmen":[…]}.
• POST h/<cid>/tx?tok=… – skicka, text/plain, en ram eller en array med högst 20 ramar; svar 204.
• POST h/<cid>/zu?tok=… – stäng (via sendBeacon).

Widgeten försöker först med SSE; om ingen första ram kommer inom 5 sekunder (till exempel för att en proxy buffrar) växlar den till långpollning. Den behandlar fel som 404 (unbekannt), 403, 413 eller 429 som en bruten anslutning och försöker igen efter en väntetid. Efter 60 sekunder utan anrop stänger servern anslutningen. CORS: Access-Control-Allow-Origin speglar ursprunget, utan inloggningsuppgifter; ursprungskontrollen sker i init, som med WebSocket.

Krav på din sida:

• connect-src i din CSP innehåller chattadressen med wss:// och https://.
• Brandväggar och proxys tillåter anrop som varar minst 30 sekunder.
• Din egen proxy släpper igenom /rc_wss/ utan buffring (nginx proxy_buffering off och proxy_cache off, Apache flushpackets=on, Caddy flush_interval -1) och skriver inte /rc_wss/h/ till åtkomstloggen (token i frågesträngen). Se Egen domän.

Lagras i webbläsaren: bara posten rc_http i sessionStorage med tidpunkten för HTTPS-anslutningen, utan personuppgifter.

Vilken väg är aktiv

På nätverksfliken i utvecklarverktygen:

• WebSocket: en anslutning av typen WebSocket till wss://ws.reactive.chat/rc_wss/ (eller din underdomän). I ramarna ser du init, init_ok, ping/pong och meddelandena.
• HTTP-reserv: först h/auf, sedan ett långvarigt …/sse (eller återkommande …/poll) och ett …/tx för varje skickat meddelande.

Nästa: Gränser och kvoter · Felsökning