Widget JS API

HTMLcopy<script>
  // Configuration — set before the widget script loads
  window.SvyazioConfig = {
    orgId: "YOUR_ORG_ID"
  };
  window.Svyazio = window.Svyazio || function() {
    (window.Svyazio.q = window.Svyazio.q || []).push(arguments);
  };
</script>
<script async src="https://app.svyazio.ru/widget/svyazio.js"></script>

The window.SvyazioConfig object (or alias window.SvyazioSetup) must be set before the script loads. Parameters override settings from the admin panel.

Appearance

Parameter	Type	Default	Description
buttonStyle	'round' | 'tab'	'round'	Chat button style.
buttonPosition	string	'br'	Button position: bl, bc, br, lt, lm, lb, rt, rm, rb.
buttonSize	number	60	Round button size (px).
chatWidth	number	400	Chat window width (min. 280px).
chatHeight	number	600	Chat window height (min. 300px).
zIndex	number	999999	Widget z-index.
accentColor	string	from settings	Accent color, e.g. '#6C63FF'.
colors	object	—	Color scheme (see setColors).

Behavior

Parameter	Type	Default	Description
startHidden	boolean	false	Hide widget on load. Show it with Svyazio('show').
disabledOnMobile	boolean	false	Do not show on mobile devices.
mobileOnly	boolean	false	Show only on mobile devices.
disableChatOpenHash	boolean	false	Disable URL hash #svyazioChatExpanded control.
deferredLoading	boolean	false	Load widget after full page load.
customWidgetButton	string	—	CSS selector for custom button. Default button is hidden.

Widget Text

Parameter	Type	Description
headerText	string	Chat window header title.
welcomeText	string	Welcome text on first open.
onlineTitle	string	Subtitle when agents are online.
offlineTitle	string	Subtitle when agents are offline.
offlineText	string	Text when no one is online.

Language & Locale

Parameter	Type	Description
locale	string | object	Language code ('ru', 'en', 'es', 'pt') or an object with interface string overrides.
language	string	Alias for locale.

Visitor Data

Parameter	Type	Description
clientId	string	Unique user ID from your system — merges history across devices and sessions.
groupId	string	Department ID for routing conversations (Settings → Departments).

Callbacks

Parameter	Type	Description
onNewMessage	function(msg)	On each new message. msg: { id, text, createdAt, type }
onAnalyticEvent	function(eventName)	On widget analytic events.

Full configuration example:

JScopywindow.SvyazioConfig = {
  orgId: "YOUR_ORG_ID",
  buttonPosition: "br",
  chatWidth: 380,
  startHidden: true,
  language: "en",
  groupId: "abc123",
  clientId: "user_42",
  headerText: "Support Team",
  colors: { buttonBg: "#6C63FF", buttonText: "#fff" },
  onNewMessage: function(msg) {
    console.log("New:", msg.text, "from", msg.type);
  }
};

An alternative to the setIntegrationData method — pass user data before the widget loads.

HTMLcopy<script>
  window.SvyazioIntegration = {
    name: "John Smith",
    email: "john@example.com",
    phone: "+1 555 000-0000",
    plan: "pro",    // custom fields
    userId: "12345"
  };
</script>
<script async src="https://app.svyazio.ru/widget/svyazio.js"></script>

Add the hash #svyazioChatExpanded to any link — clicking it will automatically open the chat:

HTMLcopy<a href="#svyazioChatExpanded">Contact us</a>

<button onclick="location.hash='#svyazioChatExpanded'">Ask a question</button>

JScopySvyazio('openChat');
Svyazio('openChat', true); // with focus

JScopySvyazio('expandWidget', true);

JScopySvyazio('minimizeWidget');
Svyazio('closeChat'); // alias

JScopySvyazio('hide');

JScopySvyazio('show');

JScopySvyazio('setIntegrationData', {
  name: "John Smith",
  email: "john@example.com",
  phone: "+1 555 000-0000",
  plan: "pro",
  userId: "12345"
});

JScopySvyazio('updateIntegrationData', { email: "new@example.com" });
Svyazio('updateIntegrationData', { phone: null }); // delete

JScopySvyazio('setButtonPosition', 'bl'); // bottom left
Svyazio('setButtonPosition', 'rt'); // top right

JScopySvyazio('setButtonSize', 72);

JScopySvyazio('setChatWidth', 480);

JScopySvyazio('setChatHeight', 700);

JScopySvyazio('setZIndex', 100);

JScopySvyazio('setColors', {
  buttonBg: '#6C63FF',
  buttonText: '#fff',
  clientBubbleBg: '#e8e5ff',
  agentBubbleBg: '#f4f4f5'
});

JScopySvyazio('resetColors');

JScopySvyazio('setLanguage', 'en');
Svyazio('setLanguage', 'es');

JScopySvyazio('setLocale', 'en');
Svyazio('setLocale', {
  placeholder: 'Type your message…',
  headerTitle: 'Support'
});

JScopySvyazio('sendAutoMessage', 'Hi! Need help with your order?');

JScopySvyazio('pageView');

JScopySvyazio('setGroupId', 'sales_dept_id');
Svyazio('setGroupId', null); // reset

JScopySvyazio('restart');

JScopySvyazio('kill');

onNewMessage

JScopywindow.SvyazioConfig = {
  orgId: "YOUR_ORG_ID",
  onNewMessage: function(msg) {
    // msg.id, msg.text, msg.createdAt (ms), msg.type: "agent"|"client"|"bot"
    console.log(msg);
  }
};

// Example: unread counter in the page title
let unread = 0;
window.SvyazioConfig.onNewMessage = function(msg) {
  if (msg.type === 'agent' || msg.type === 'bot') {
    document.title = '(' + (++unread) + ') ' + document.title;
  }
};

onAnalyticEvent

JScopywindow.SvyazioConfig = {
  orgId: "YOUR_ORG_ID",
  onAnalyticEvent: function(eventName) {
    // Google Analytics 4
    gtag('event', eventName, { event_category: 'Live Chat' });

    // Mixpanel / Amplitude
    if (window.mixpanel) {
      mixpanel.track('chat_' + eventName);
    }
  }
};

Show chat after N seconds

JScopysetTimeout(function() {
  Svyazio('show');
  Svyazio('openChat');
}, 15000);

Pass data after login

JScopyfunction onUserLogin(user) {
  Svyazio('setIntegrationData', {
    name: user.name,
    email: user.email,
    plan: user.plan,
    clientId: 'user_' + user.id
  });
}

Route VIP clients to priority department

JScopyif (currentUser.plan === 'enterprise') {
  Svyazio('setGroupId', 'vip_dept_id');
}

Hide on specific pages

JScopyif (window.location.pathname === '/checkout') {
  Svyazio('hide');
} else {
  Svyazio('show');
}

Custom button

HTMLcopy<button id="my-chat-btn">Contact Support</button>

<script>
  window.SvyazioConfig = {
    orgId: "YOUR_ORG_ID",
    customWidgetButton: "#my-chat-btn"
  };
</script>

clientId — history across devices

JScopywindow.SvyazioConfig = {
  orgId: "YOUR_ORG_ID",
  clientId: "user_" + currentUser.id
};

Most Chatra JS API methods are supported in Svyazio. Migrating your code requires only renaming objects and calls:

1. Replace ChatraSetup → SvyazioSetup
2. Replace ChatraIntegration → SvyazioIntegration
3. Replace all calls Chatra('method') → Svyazio('method')

Method	Arguments	Description
openChat	focus?	Open chat
expandWidget	focus?	Open (desktop only)
minimizeWidget	—	Collapse chat
closeChat	—	Alias for minimizeWidget
hide	—	Hide widget
show	—	Show widget
setIntegrationData	data	Set visitor data (overwrite)
updateIntegrationData	data	Update visitor data (merge)
setButtonPosition	code	Move button
resetButtonPosition	—	Reset to config position
setButtonSize	size	Button size (px)
setChatWidth	width	Window width (px)
setChatHeight	height	Window height (px)
setZIndex	value	Widget z-index
setColors	colors	Override colors
resetColors	—	Reset colors
setLanguage	code	Switch language
setLocale	code | object	Language or string overrides
sendAutoMessage	text	Auto message from bot
pageView	—	Track page (SPA)
setGroupId	id | null	Route to department
restart	—	Restart widget
kill	—	Destroy widget