Як додати
Додайте вашого агента на будь-який сайт через діалог «Configure Widget» у налаштуваннях агента. Крок 1: Відкрийте налаштування агента, натиснувши іконку шестерні у верхньому правому куті редактора агента.



Типи віджетів
Кожен вбудований віджет — або голосовий, або чатовий; тип обирається в діалозі Configure Widget. Обидва типи підтримують усі три режими вбудовування.
Як поводяться чат-розмови:
- Розмова починається, коли відвідувач відкриває чат (натискає кнопку чату) — агент вітається першим. Саме завантаження сторінки ніколи не починає розмову.
- Чат-сесія триває до 1 години. Коли вона завершується, відвідувачу пропонується кнопка Start new chat, яка починає нову розмову.
- Перезавантаження сторінки починає нову розмову при наступному відкритті — історія чату не зберігається між завантаженнями сторінки.
- Кожна розмова враховується один раз у ліміт використання embed-токена, так само як один голосовий дзвінок.
- Чат-розмови відображаються в історії дзвінків агента з повним транскриптом.
Режими вбудовування
Передумови
Стосуються всіх трьох режимів:- Голосові віджети: обслуговуйте сторінку через HTTPS або з
http://localhost. Браузери відмовляють у доступі до мікрофона на звичайних HTTP-джерелах чиfile://. Для чат-віджетів вимоги до мікрофона немає, хоча HTTPS усе одно рекомендований. - Якщо в кабінеті задано Allowed Domains, додайте туди й ваш тестовий домен (наприклад,
localhost) — інакше запити віджета будуть відхилені. Залиште список порожнім, щоб дозволити всі домени. - Код вбудовування, який ви копіюєте з кабінету, — це один тег
<script>, що завантажуєdograh-widget.jsасинхронно. Віджет автоматично ініціалізується після завантаження й надаєwindow.DograhWidget. Код, що реєструє колбеки, має дочекатись доступності віджета.
Pass context to the agent
Your page usually knows something about the visitor — their name, plan, cart value, the article they were reading. Pass it along and your agent can use it from the first word. The snippet you copy from the dashboard carries adata-dograh-context attribute — a JSON object of details about the visitor. The snippet is a small bootstrap function: js is the widget <script> element it creates, and the context is attached to that element before it is added to the page. The relevant part of the generated snippet looks like this (keep the generated js.src value, which contains your embed token):
JSON.stringify(...) in the generated snippet, for example:
{{initial_context.<name>}}:
Update context after the page loads
The attribute is fixed at page load, which doesn’t fit a single-page app — the visitor logs in, changes route, or fills a cart long after the snippet ran. For that, callsetContext():
getContext() returns the current set.
Context is read when a conversation starts, so setContext() applies to the next conversation — calling it mid-call or mid-chat doesn’t change the one in progress (the widget logs a console warning if you do). For chat widgets, “next” includes the fresh conversation started by Start new chat after a session expires.
The widget script loads asynchronously, so
window.DograhWidget may not exist yet when your app’s code first runs. Call setContext() from an event that fires after load — a window.load listener, or a user action like clicking your own “Chat with us” button. See Lifecycle callbacks for the same timing rule.data-dograh-context for what the page knows at render, setContext() for what it learns later. They merge, and setContext() wins on a repeated name.
Limits, applied per conversation: up to 50 variables, 64 characters per name, 2000 characters per value, and 8 KB in total. Anything past a limit is dropped and the conversation still starts. The names provider and runtime_configuration are reserved and ignored.
Floating Widget

- Voice: клік на кнопку (іконка мікрофона + текст) починає дзвінок; повторний клік — завершує. Кнопка автоматично оновлює підпис і колір упродовж дзвінка: налаштований текст → «Connecting…» → «End Call» → «Retry» у разі помилки.
- Chat: клік на кнопку (іконка чату + текст) відкриває чат-панель, закріплену в тому ж кутку; агент вітає відвідувача першим, і розмова відбувається в панелі. Клік на кнопку (або на × панелі) закриває панель, не завершуючи розмову — при повторному відкритті показується той самий транскрипт.
Inline Component

<div>, який ви розміщуєте на сторінці.
- Voice: панель статусу (іконка статусу + текст статусу + кнопка CTA). Зміни статусу оновлюють панель на місці.
- Chat: спочатку екран із закликом до дії; клік на кнопку замінює його чат-панеллю, що заповнює контейнер. Додатковий JavaScript не потрібен.
Звичайний HTML
Розмістіть контейнер<div> там, де має рендеритись віджет. Віджет автоматично приєднається до нього.
React
Оскільки React монтується вже після того, як скрипт віджета міг завантажитись, інтегруйте черезinitInline при першому монтуванні та refresh при повторному. Опитуйте наявність window.DograhWidget, щоб урахувати асинхронне завантаження скрипта.
Headless Mode

JavaScript API (voice widgets)
Усі сетери
on* — одноразові (single-listener): повторний виклик того самого замінює попередній обробник.
JavaScript API (chat widgets)
In chat mode
start() aliases startChat() and end() is a no-op teardown (chat sessions need none), so generic snippets keep working. Sends are serialized — sendMessage while a reply is pending (waiting) resolves to null.
Про час завантаження. Скрипт віджета завантажується асинхронно, тож
window.DograhWidget може бути ще недоступний у момент першого виконання вашого вбудованого <script>. Приклади нижче припускають, що window.DograhWidget уже доступний у момент реєстрації. Щоб це гарантувати:- Звичайний JS: обгорніть код реєстрації в
window.addEventListener('load', () => { /* реєстрація тут */ }). - React: всередині
useEffectреєструйтесь одразу, якщоdocument.readyState === 'complete', інакше додайте одноразовий слухачwindow.load, що реєструє при спрацюванні. - Обробники кліків, що викликають
start()/end(), не потребують захисту — на момент кліку користувача віджет уже давно завантажений.
Vanilla JS
React + TypeScript
start() має виконуватись усередині справжнього обробника користувацької дії (click, touchend тощо). Браузери відмовляються надавати доступ до мікрофона скриптам, що запитують його поза таким обробником — виклик start() з setTimeout чи при завантаженні сторінки завершиться помилкою дозволу.Колбеки життєвого циклу (усі режими)
Колбекиon* з Headless JavaScript API працюють у всіх трьох режимах вбудовування, а не лише в Headless. Використовуйте їх для аналітики або запуску інтерфейсу на сторінці навіть тоді, коли віджет рендерить власний інтерфейс (Floating чи Inline). Колбеки дзвінка (onCall*) спрацьовують для голосових віджетів; для чат-віджетів так само використовуйте onMessage і onChatStateChange.
onCallConnected і onCallDisconnected спрацьовують лише тоді, коли дзвінок дійсно встановлює медіа-з’єднання — невдалі спроби з’єднання (наприклад, відмова в доступі до мікрофона, збій мережі) їх не запускають, тож аналітика лишається чистою.
