Skip to main content

Як додати

Додайте вашого агента на будь-який сайт через діалог «Configure Widget» у налаштуваннях агента. Крок 1: Відкрийте налаштування агента, натиснувши іконку шестерні у верхньому правому куті редактора агента. Відкрийте налаштування агента Крок 2: Прокрутіть до розділу Add to Website і натисніть Configure Widget. Перейдіть до Add to Website Крок 3: Увімкніть вбудовування, додайте домен вашого сайту в Allowed Domains, оберіть Widget Type (Voice або Chat) і режим вбудовування (Floating Widget, Inline Component або Headless (Bring Your Own UI)), за потреби налаштуйте кнопку (позицію, колір, текст) і натисніть Save Configurations. Збережіть налаштування Крок 4: Скопіюйте згенерований код і вставте його на вашу сторінку, щоб протестувати агента. Скопіюйте код вбудовування

Типи віджетів

Кожен вбудований віджет — або голосовий, або чатовий; тип обирається в діалозі 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.
Context Key names cannot contain dots, whitespace, pipes, or braces because those characters have structural meaning in template expressions. Invalid entries are dropped without preventing the conversation from starting.
The snippet you copy from the dashboard carries a data-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):
Because it’s built in JavaScript at page load, you can put anything your page knows in it — a logged-in customer’s name, their plan, cart contents. Replace the object inside JSON.stringify(...) in the generated snippet, for example:
Each key is then available in any node prompt as {{initial_context.<name>}}:
Values can be strings, numbers, booleans, or nested objects. This works for voice and chat widgets alike, and the values are recorded on the conversation so you can see what the agent was given.

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, call setContext():
Each call merges into the context already collected, so you can add details as they arrive and re-send a name to correct it. 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.
Use whichever fits: 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.
Context comes from the page, so a visitor can both read it and change it before it reaches your agent. Never pass secrets, and don’t let it gate what the agent will do or disclose — treat plan: "pro" as a hint for phrasing, not proof of entitlement. For data the agent must trust, pass an opaque id like customer_id and let Dograh fetch the real details from your API with Pre-Call Data Fetch.
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

Floating widget показано в кутку сторінки Рендерить кнопку-пігулку, закріплену в кутку сторінки.
  • Voice: клік на кнопку (іконка мікрофона + текст) починає дзвінок; повторний клік — завершує. Кнопка автоматично оновлює підпис і колір упродовж дзвінка: налаштований текст → «Connecting…» → «End Call» → «Retry» у разі помилки.
  • Chat: клік на кнопку (іконка чату + текст) відкриває чат-панель, закріплену в тому ж кутку; агент вітає відвідувача першим, і розмова відбувається в панелі. Клік на кнопку (або на × панелі) закриває панель, не завершуючи розмову — при повторному відкритті показується той самий транскрипт.
Налаштуйте Button Text, Button Color і Position (верх/низ + ліворуч/праворуч) у кабінеті. Сторінка не потребує жодного власного JavaScript — вставка коду вбудовування і є всією інтеграцією. Якщо потрібно підписатись на події життєвого циклу дзвінка (наприклад, для аналітики), дивіться Колбеки життєвого циклу нижче.

Inline Component

Inline widget, вбудований у розділ сторінки Рендерить панель всередині <div>, який ви розміщуєте на сторінці.
  • Voice: панель статусу (іконка статусу + текст статусу + кнопка CTA). Зміни статусу оновлюють панель на місці.
  • Chat: спочатку екран із закликом до дії; клік на кнопку замінює його чат-панеллю, що заповнює контейнер. Додатковий JavaScript не потрібен.
Налаштуйте Button Text, Button Color і Call to Action Text у кабінеті.

Звичайний HTML

Розмістіть контейнер <div> там, де має рендеритись віджет. Віджет автоматично приєднається до нього.

React

Оскільки React монтується вже після того, як скрипт віджета міг завантажитись, інтегруйте через initInline при першому монтуванні та refresh при повторному. Опитуйте наявність window.DograhWidget, щоб урахувати асинхронне завантаження скрипта.

Headless Mode

Headless widget, кероване інтерфейсом сторінки У режимі Headless віджет не додає жодного власного інтерфейсу. Ви самі рендерите будь-які кнопки, банери чи чат-інтерфейси й керуєте агентом через JavaScript API.

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 спрацьовують лише тоді, коли дзвінок дійсно встановлює медіа-з’єднання — невдалі спроби з’єднання (наприклад, відмова в доступі до мікрофона, збій мережі) їх не запускають, тож аналітика лишається чистою.