Before you start
Every integration talks to a Chatting App - one per website or mobile app. Ask your Connectly workspace admin to create one (Desk → Chatting App) and send you:
- Public key (
pk_…) - identifies your app. Safe to ship in a web page or app binary. - Secret key - only if you sign in your own users (see Identified visitors). Keep it on your server, never in the client.
- Server URL -
https://connectly.wowdigital.sa(used for both the API and the realtime connection).
https://www.your-site.com). Ask for your production and staging addresses to be added.Installation
Add one script tag to your page. No build step or package manager needed.
<script src="https://connectly.wowdigital.sa/assets/connectly/chatting-sdk/connectly-chat.js"></script>socket.io-client by itself. If your page already includes socket.io-client v4, that copy is used.Show the chat
ConnectlyChatWidget is a complete chat: messages, images, files, voice notes, typing indicator and the "talk to a human" flow. Add a wrapper element to your page and mount the chat into it - it fills the element.
<div id="support-chat" style="height: 600px"></div>
<script src="https://connectly.wowdigital.sa/assets/connectly/chatting-sdk/connectly-chat.js"></script>
<script>
const widget = ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat", // the wrapper element's id
title: "Support",
});
</script>container can also be a CSS selector or the element itself.Floating chat button
Leave out container to get a round chat button in the corner of the page instead. It opens the chat above it (full screen on phones) and shows a badge for unread replies. It connects only when the visitor first opens it.
const widget = ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
position: "right", // or "left"
startOpen: false,
});
widget.open(); // open the chat from your own "Contact us" button
widget.close(); // minimise it - the conversation continues
widget.destroy(); // remove it and end the conversationapiBaseUrl and wsUrl default to the server the script is loaded from (https://connectly.wowdigital.sa). Set them only if you host connectly-chat.js yourself.Customize
Match your brand with theme, and switch features or change any text with options. Pass only what you want to change. The names are the same as the Flutter SDK's ConnectlyChatTheme and ConnectlyChatOptions; times are in milliseconds.
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
theme: {
primaryColor: "#16A34A",
headerBackgroundColor: "#16A34A",
visitorBubbleColor: "#16A34A",
backgroundImage: "https://www.your-site.com/chat-bg.png",
bubbleBorderRadius: 16,
},
options: {
enableAttachments: true,
enableVoiceRecording: false,
enableTalkToHuman: true,
welcomeMessage: "Hi! How can we help you today?",
inputPlaceholder: "Type a message...",
},
});Options
| Option | Default | Description |
|---|---|---|
enableAttachments | true | Attach files and images |
enableVoiceRecording | true | Record voice messages (shown on HTTPS pages, in browsers that can record) |
enableTalkToHuman | true | Show "Talk to a human" in the chat |
enableTypingIndicator | true | Animated dots while the other side types |
enableSounds | true | A soft chime when a message arrives |
allowedFileExtensions | png, jpg, jpeg, gif, webp, pdf, doc, docx, txt | Pickable file types |
maxFileSizeBytes | 10485760 (10 MB) | Largest attachment |
maxRecordingDuration | 120000 (2 min) | Longest voice note, in milliseconds |
messageCharacterLimit | 2000 | Longest text message (0 = no limit) |
typingThrottle | 2000 | How often "typing" is sent while the visitor types, in milliseconds |
resumeInterruptedChatWithin | 1800000 (30 min) | If the page is reloaded or closed while the chat is open, coming back within this time continues the same chat (0 = off) |
direction | "auto" | "ltr", "rtl", or "auto" to follow the page's <html dir> |
welcomeMessage, inputPlaceholder, …Label | English text | Every visible text can be replaced - e.g. with your translations (see below) |
Theme
| Property | Default | Description |
|---|---|---|
primaryColor | #4F46E5 | Send button, chat button, highlights |
backgroundColor | #F3F4F6 | Behind the messages |
backgroundImage | null | Image behind the messages: a URL, or { url, fit, opacity } with fit "cover", "contain" or "repeat" |
visitorBubbleColor / visitorTextColor | #4F46E5 / #FFFFFF | The visitor's own messages |
otherBubbleColor / otherTextColor | #F1F1F4 / rgba(0,0,0,.87) | Messages from the AI and agents |
bubbleBorderRadius | 16 | Bubble corners: pixels, or any CSS value like "16px 16px 4px 16px" |
headerBackgroundColor / headerTextColor | #4F46E5 / #FFFFFF | The title bar |
messageTextStyle / timestampTextStyle | null | CSS properties, e.g. { fontSize: "15px" } |
fontFamily | System fonts | Font of the whole chat |
composerBackgroundColor / inputTextColor | #FFFFFF / #111827 | The message box area |
Texts and Arabic
Every text the chat shows is an option: title, welcomeMessage, inputPlaceholder, talkToHumanLabel, talkToHumanHint, connectingLabel, onlineLabel, waitingForAgentLabel, agentConnectedLabel, agentLeftLabel, connectionLostLabel, connectErrorLabel, retryLabel, rateLimitedLabel, notSentLabel, fileTooLargeLabel, fileTypeNotAllowedLabel, microphonePermissionLabel, recordingLabel, recordingTooShortLabel, loadMessagesFailedLabel, attachmentLabel. {seconds}, {size} and {max} in a text are replaced with the actual value.
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
title: "تواصل معنا",
options: {
direction: "rtl",
welcomeMessage: "أهلاً بك! كيف نقدر نساعدك؟",
inputPlaceholder: "اكتب رسالتك...",
onlineLabel: "متصل",
connectingLabel: "جارٍ الاتصال...",
talkToHumanHint: "تحتاج موظفاً؟",
talkToHumanLabel: "التحدث مع موظف",
waitingForAgentLabel: "جارٍ تحويلك إلى موظف...",
agentConnectedLabel: "أنت الآن تتحدث مع موظف",
agentLeftLabel: "غادر الموظف المحادثة. المساعد الذكي عاد لمساعدتك.",
notSentLabel: "لم تُرسل. اضغط لإعادة المحاولة",
rateLimitedLabel: "أنت ترسل بسرعة كبيرة. حاول بعد {seconds} ثانية.",
retryLabel: "إعادة المحاولة",
},
});Callbacks
Hook into the chat without building your own UI:
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
onChatStarted: (chatId) => localStorage.setItem("my_chat_id", chatId), // keep it to resume later
onMessageReceived: (m) => console.log(m.role, m.content),
onMessageSend: (m) => analytics.track("chat_send", { type: m.type }),
onMessageStatusChanged: (m) => console.log(m.id, m.status), // "sent" or "failed"
onClose: () => console.log("chat closed"),
});Messages have the same fields as in Custom UI: id, role, type, content, file, timestamp and status.
Conversations
Each time the widget is mounted a new conversation starts. If the visitor reloads the page (or leaves and comes back) while a chat is open, it continues within resumeInterruptedChatWithin. Minimising the floating chat never ends it; destroy() does. To continue a specific conversation, save the id from onChatStarted and pass it back as chatId - its earlier messages load automatically.
// Open the conversation the visitor had before (null = start a new one):
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
chatId: localStorage.getItem("my_chat_id"),
onChatStarted: (chatId) => localStorage.setItem("my_chat_id", chatId),
});Identified visitors
Signed-in users can be linked to their account, so agents see who they're talking to and the user's chats follow them across devices. Your backend signs a short-lived token with the app's secret key - never the browser.
// In the browser - get a short-lived token from YOUR backend, then pass it in:
const { identify_token } = await fetch("/api/chat-token").then((r) => r.json());
ConnectlyChatWidget.mount({
publicKey: "pk_xxx",
container: "support-chat",
identifyToken: identify_token,
});| Claim | Required | Purpose |
|---|---|---|
user_id | Yes | Your user's id |
exp | Yes | Expiry (Unix time) - keep it short, e.g. 5 minutes |
name, email, phone | No | Shown to agents |
Signed with HS256 using the Chatting App's secret key:
const jwt = require("jsonwebtoken");
app.get("/api/chat-token", requireLogin, (req, res) => {
const token = jwt.sign(
{ user_id: req.user.id, name: req.user.name, email: req.user.email },
process.env.CONNECTLY_SECRET_KEY,
{ algorithm: "HS256", expiresIn: "5m" }
);
res.json({ identify_token: token });
});import time, jwt # PyJWT
@app.get("/api/chat-token")
def chat_token(user=Depends(require_login)):
token = jwt.encode(
{"user_id": user.id, "name": user.name, "email": user.email,
"exp": int(time.time()) + 300},
CONNECTLY_SECRET_KEY,
algorithm="HS256",
)
return {"identify_token": token}Built-in behavior
- Instant messages: messages appear right away with 🕓, then ✓ - or "Not sent, tap to retry". Retries are never delivered twice.
- Files and voice notes: images show in the chat, documents open in a new tab, and voice notes - recorded right in the browser - play inline. While the AI reads an upload, the typing dots show.
- Silent reconnecting: if the connection drops (laptop sleep, tab in the background, network change), the chat returns to the same conversation and loads anything missed. A Retry bar appears only if that fails.
- Human handoff: "Talk to a human" sits above the message box, shows a waiting line once asked, and hides while an agent is in the chat.
- Limits: up to 15 messages per minute per visitor; past that the message shows "Not sent" with how long to wait.
- Your styles stay yours: the chat is isolated (Shadow DOM) - your page's CSS doesn't change it, and it doesn't change your page.
- Footer: the chat shows a small "Powered by Connectly" line under the message box.
API reference
ConnectlyChatWidget.mount(config)
| Option | Description |
|---|---|
publicKey | Required. The Chatting App's public key |
container | Wrapper element id, CSS selector or element to fill. Omit for a floating chat button |
title | Header title (default "Chat with us") |
theme | Colors and look - see Customize |
options | Features, limits and texts - see Customize |
identifyToken | Token from your backend for a signed-in user |
chatId | Resume this conversation |
position, startOpen | Floating button only: "right" or "left" corner; open right away |
onChatStarted, onMessageReceived, onMessageSend, onMessageStatusChanged, onClose | See Callbacks |
apiBaseUrl, wsUrl | Only if you host the script yourself - default to the server it's loaded from |
| Method | Description |
|---|---|
open() | Opens the floating chat |
close() | Minimises the floating chat (the conversation continues) |
toggle() | Opens or closes it |
destroy() | Removes the chat and ends the conversation |
client | The ConnectlyChat it runs on - for listening to its events |