Integration: technical reference for developers

This reference is for developers who build reactive.chat into a website, an app or a backend. It describes interfaces and flows as they are implemented in the code – with names, types, defaults and error cases.

How to set up appearance, texts, start screen, rules, tours, A/B tests and the AI persona is described under Customisation. How to use your account and the desk is described in the Manual.

At a glance

Your visitors' browser                      reactive.chat                         your server
----------------------                      -------------                         -----------
loader.js  --(trigger)-->   core.<hash>.js  cdn.reactive.chat
   window.ReactiveChat (API, events)
   WebSocket rc.v1  <------------------->   ws.reactive.chat/rc_wss/
   HTTP fallback (SSE/Poll) <----------->   ws.reactive.chat/rc_wss/h/
                                            chat server  --- POST (signed) ---->  customer data endpoint
                                                         --- POST (signed) ---->  webhook receiver
                                            reactive.chat/v1  <--- Bearer -----  REST API / MCP
identify(userHash)  <-------------------------------------- HMAC-SHA256 ------  identity secret

On the client side you embed a script tag and optionally control the widget through window.ReactiveChat. On the server side you sign the identity of signed-in users, answer customer data requests if needed, receive webhooks and use the REST API.

Chapters

Basics

• Architecture and flow – the parts, how they work together, versions and delivery
• Quick start – embed, enter your domain, CSP, check

In the browser

• Script tag reference – all data-rc-* attributes and configuration sources
• JavaScript API – all commands of ReactiveChat(…)
• Events – on/off and DOM events
• Identifying visitors and passing context – identify, userHash, exp, track
• Single-page apps and page changes
• Security and Content Security Policy

Connection and delivery

• Own domain and first-party proxy – nginx, Apache, Caddy
• Transport: WebSocket, HTTP fallback, reconnecting – protocol, error and close codes

On your server

• Customer data endpoint – fetching and importing orders
• Webhooks – events, signature, retries, REST hooks
• Server API (REST v1) and MCP
• Integrations and channels – WhatsApp, Messenger, Instagram, Telegram, SMS, email

Other places to build it in

• Mobile apps – the chat in a WebView
• Smart Answer – AI answer in your website search

Operation

• Privacy integration – consent, storage, privacy text
• Limits and quotas
• Troubleshooting and checklist

Further pages on the topic

• Embedding the widget – the short version
• Technical detail – measurements of size, accessibility and contrast
• Open the chat from your own link or button
• The promo card in the chat
• Customer data in the chat
• Own domain (first-party)
• HTTP fallback
• Insert the privacy text automatically

Terms

• Site key – the public key of a project (24 characters), included in the snippet. Not a secret.
• Project – a website or app with its own settings; several projects form a workspace.
• Desk – the interface in which your team replies.
• Confirmed user – a visitor whose identity your server has signed via userHash.
• Loader / core – the small loading part loader.js and the main part core.<hash>.js loaded after it.

All parts of the documentation at a glance: Documentation.