Сайт виджеттері

Келушілер дауыстық сөйлесуді тікелей браузерден бастай алатындай дауыстық агентіңізді кез келген веб-сайтқа кірістіріңіз. Widgets қойындысы embed кодтарын, теңшеу опцияларын және домен қауіпсіздігі параметрлерін ұсынады.

Callback виджетін іздеп жүрсіз бе?

Callback Widget осы беттегі виджеттерден мүлдем басқаша жұмыс істейді — браузердегі дауыстық қоңырауды бастаудың орнына, ол келушінің телефон нөмірін жинап, агентіңізге оларға кері қоңырау шалдырады. Арнайы Callback Widget бетін қараңыз.

Виджет түрлері

Hanc.AI төрт браузердегі виджет түрін ұсынады, оған қоса телефон кері қоңыраулары үшін бөлек Callback Widget:

Виджет	Тег атауы	Сипаттама	Ненің үшін жақсы
Floating Widget	`hanc-ai-floating-call`	Бетіңіздің үстінде қалқып тұратын шар батырма	Әрдайым көрінетін әрекетке шақыру
Pill Widget	`hanc-ai-pill-call`	Мазмұныңызда жолшыбай орналастырылған ықшам пилюля пішінді батырма	Бар макет ішіндегі минималды із
Pill Floating Widget	`hanc-ai-pill-floating-call`	Pill сияқты ықшам пилюля пішіні, бірақ Floating виджеті сияқты бетпен бірге қалқиды	Келуші айналдырғанда оны ертіп жүретін пилюля эстетикасын қалағанда
Inline Widget	`hanc-ai-inline-call`	Бет мазмұнына кірістірілген толық өлшемді қоңырау батырмасы	Арнайы "Talk to Us" бөлімдері
Callback Widget	`hanc-ai-callback`	Телефон нөмірі формасы; агент келушіге кері қоңырау шалады	Лид жинайтын беттер, жоғары ниетті лендинг беттер — Callback Widget қараңыз

Ортақ атрибуттар

Барлық виджет түрлері мына негізгі атрибуттарды қолдайды:

Атрибут	Міндетті	Сипаттама	Әдепкі
`agent-id`	Иә	Агентіңіздің бірегей идентификаторы	—
`voice-service-url`	Жоқ	Дауыс қызметінің URL-ін қайта анықтау	Авто-анықталады
`api-base-url`	Жоқ	API базалық URL-ін қайта анықтау	Авто-анықталады

Дисплей атрибуттары

Атрибут	Сипаттама	Мәндер	Әдепкі
`position`	Беттегі виджет орны	`bottom-right`, `bottom-left`, `top-right`, `top-left`, `static`	`bottom-right`
`size`	Виджет өлшемі пиксельмен	Сан	`120`
`theme`	Түс тақырыбының атауы	Түс тақырыптары қараңыз	`default`

Батырма мәтіні атрибуттары

Атрибут	Сипаттама	Әдепкі
`button-start-text`	Күту режиміндегі батырмада көрсетілетін мәтін	`"Call"`
`button-connecting-text`	Қосылу кезінде көрсетілетін мәтін	`"Connecting..."`
`button-end-text`	Белсенді қоңырау кезінде көрсетілетін мәтін	—

Terms атрибуттары

Атрибут	Сипаттама	Әдепкі
`terms-enabled`	Қоңырау алдында келісім диалогын қосу	`false`
`terms-content`	Markdown пішіміндегі келісім мәтіні	`""`
`terms-url`	Terms & Conditions бетіне сілтеме	`"https://hanc.ai/terms"`
`privacy-url`	Privacy Policy бетіне сілтеме	`"https://hanc.ai/privacy"`

ақпарат

HTML элементінде орнатылған Terms атрибуттарын, skip-fetch true мәніне орнатылмаған болса, API-дан алынған агенттің виджет параметрлері қайта анықтайды.

Дыбыс атрибуттары

Атрибут	Сипаттама	Әдепкі
`sound-enabled`	Қоңырау басталу/аяқталу дыбыстарын қосу	`true`
`sound-volume`	Дыбыстық эффект дауысы	`0.25`
`sound-preset`	Дыбыс алдын ала орнату идентификаторы	`"1"`

Түс тақырыптары

Виджет көрінісін 11 кіріктірілген түс тақырыбымен теңшеңіз:

Тақырып	Мәні
Default	`default`
Purple	`purple`
Blue	`blue`
Cyan	`cyan`
Emerald	`emerald`
Amber	`amber`
Tangerine	`tangerine`
Rose	`rose`
Ember	`ember`
Black	`black`
White	`white`

Әр тақырыптың қараңғы да, ашық та нұсқалары бар. Тақырыпты embed кодындағы theme атрибуты арқылы орнатыңыз немесе оны агенттің виджет параметрлерінде конфигурациялаңыз.

Кірістіру мысалдары

<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

<hanc-ai-floating-call
  agent-id="YOUR_AGENT_ID"
  theme="emerald"
  position="bottom-left"
  size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Виджет нұсқасын бекіту

Жоғарыдағы скрипт URL-і әрдайым соңғы шығарылған виджетті жүктейді — сайтыңыз жақсартуларды автоматты түрде қабылдайды, ал нұсқа көрсетілмегенде @latest әдепкі болады. Тұрақты шығарылымға бекіту қажет болса, қалаған нұсқаны қосу арқылы нақты бекітіңіз, мысалы https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.

Виджет оқиғалары

Виджеттер JavaScript-те тыңдай алатын оқиғаларды шығарады:

Оқиға	Сипаттама
`status-changed`	Қоңырау мәртебесі өзгергенде іске қосылады
`connecting`	Қоңырау орнатылып жатыр
`connected`	Қоңырау белсенді
`idle`	Белсенді қоңырау жоқ
`error`	Қате орын алды
`audio-track`	Қашықтағы аудио трек алынды (визуализация үшін)
`local-audio-track`	Жергілікті микрофон аудио трегі (визуализация үшін)
`microphone-enabled`	Микрофон қосылды
`microphone-disabled`	Микрофон өшірілді
`call-start`	Қоңырау сәтті басталғанда іске қосылады
`call-end`	Қоңырау аяқталғанда іске қосылады

Мысал: Оқиғаларды тыңдау

const widget = document.querySelector('hanc-ai-floating-call');

widget.addEventListener('call-start', () => {
  console.log('Call started');
});

widget.addEventListener('call-end', () => {
  console.log('Call ended');
});

Браузерден қоңырау кезінде агент сіздің сайтыңыздан бетті ашуды сұрай алады — «тарифтерді көрсетейін» — және келуші мұны әңгімені үзбей көреді.

Шешім сіздің бетіңізде қалады. Агент сұрау жібереді, оның нені білдіретінін кодыңыз шешеді. Мекенжайды ашу, қойындыны ауыстыру, бөлімге жылжу, аккордеонды жаю — бәрі жарамды жауап.

Үш қадам қажет, олардың ешқайсысы жеке жұмыс істемейді.

1-қадам — Агентке қандай беттер бар екенін айтыңыз

Агент сайтыңыздың картасын көрмейді. Ол тек өзіңіз берген жолды сұрайды — оларды агенттің промптында немесе білім базасында тізіп беріңіз:

Сайтымыздың беттері:
/pricing — тарифтер мен бағалар
/contact — байланыс формасы және телефон
/product/crm — CRM

Бұл қадамды өткізіп жіберсеңіз, агенттің сұрайтыны болмайды, сондықтан ол тіпті әрекет жасамайды.

2-қадам — Сұрауды өз бетіңізде өңдеңіз

Мұны бір рет, виджет скриптінен кейін кез келген жерге қосыңыз. Оқиға бет бойымен жоғары көтеріледі, сондықтан document — қолайлы орын:

<script>
document.addEventListener('agent-command', (event) => {
  const { type, payload } = event.detail;

  if (type === 'navigate') {
    // SPA: қайта жүктеусіз өту — қоңырау жалғасады.
    router.push(payload.path);

    // Кәдімгі сайт: екінші қойынды ашыңыз, бұл (және қоңырау) тірі қалады.
    // window.open(payload.path, '_blank');

    event.preventDefault();   // ← агентке «қабылданды» дейтін осы
  }
});
</script>

Беттің толық қайта жүктелуі қоңырауды үзеді

Қоңырау осы беттің ішінде тұр. window.location.href = … құжатты жүктеуден шығарады, әңгіме де онымен бірге кетеді — келушіні сөз ортасында үзеді. Роутеріңіз болса, клиент жағында өтіңіз; болмаса, бетті жаңа қойындыда ашыңыз. Қайта қосылу жоқ: қайта жүктеуден ештеңе аман қалмайды.

preventDefault() міндетті

Бұл «мен өңдедім» деудің жалғыз жолы. Онсыз агентке сайт навигацияны қолдамайды деп хабарланады: қоңыраудың соңына дейін ол әрекетті тоқтатады және қайда басу керегін айтуға қайта оралады. Консольде ештеңе шықпайды — бет жай ғана сұрауды елемегендей көрінеді, өйткені солай болды.

3-қадам — Тексеріңіз

Сайттан агентіңізге қоңырау шалып, бетті атымен сұраңыз. Екі нәрсе болуы тиіс: бет ашылады және агент «мәзірден табасыз» дегеннің орнына «міне, бағалар» дейді.

Агентке деректермен жауап беру

Кейбір командалар — нұсқау емес, сұрақ. Олар да солай келеді, бірақ жауап respond() арқылы беріледі:

Команда	Агент нені сұрайды	Немен жауап бересіз
`navigate`	«осы жолды аш»	ештеңемен — `preventDefault()` жеткілікті
`page_context`	«келуші не көріп тұр?»	пайдалы кез келген нәрсемен: жол, тақырып, тауар
`cart_state`	«себетінде не бар?»	позициялар, сомалар, валюта

<script>
document.addEventListener('agent-command', (event) => {
  const { type, respond } = event.detail;

  if (type === 'page_context') {
    event.preventDefault();
    respond({ path: location.pathname, title: document.title });
  }
});
</script>

preventDefault() кейін жауап беруге шамамен бір секунд бар: await жарайды, баяу API шақыруы жарамайды. Қолда барымен жауап беріңіз.

Агент нені сұрай алады, нені сұрай алмайды

Тек өз сайтыңыздың ішіндегі жолдар. Жол / таңбасынан басталуы керек. Доменнен шығуы мүмкін кез келген нәрсе — //evil.com, https://…, кері қиғаш сызықтар — бетке жетпей тұрып қабылданбайды. Агент келушілеріңізді басқа жаққа жібере алмайды.
Тек браузерден қоңыраулар. Телефон қоңырауында ашатын бет жоқ, сондықтан онда бұл командалар болмайды.
Бір бас тарту жеткілікті. Бетіңіз бірінші сұрауды растамаса, агент қоңыраудың соңына дейін сұрауды қояды. Ол қайта әрекеттенбейді және — ең бастысы — келушіге ашпаған нәрсесін аштым демейді.

Ештеңе болмай жатыр ма?

Сүзгіден өткізбес бұрын әр команданы журналға жазыңыз: document.addEventListener('agent-command', e => console.log(e.detail)). Консольде navigate көрсеңіз, агент өз ісін атқарған, демек preventDefault() немесе өз өңдеушіңіз жетіспейді. Ештеңе көрмесеңіз, агентке мұндай жолдың бар екені айтылмаған — 1-қадамға оралыңыз.

Техникалық талаптар

Виджеттер келушінің браузерінен мыналарды қолдауды талап етеді:

WebGL 2.0 — рендерлеу үшін
Web Audio API — аудио өңдеу үшін
WebRTC — нақты уақыттағы дауыстық байланыс үшін

Барлық заманауи браузерлер (Chrome, Firefox, Safari, Edge) осы технологияларды қолдайды.

Домен шектеулері

Агент виджетіңізді қай веб-сайттар кірістіре алатынын басқарыңыз.

Әрдайым рұқсат етілген домендер

Мына домендер конфигурацияға қарамастан әрдайым рұқсат етіледі:

hanc.ai (және субдомендер)
hanc.me (және субдомендер)
localhost

Барлық домендерге рұқсат ету

Әдепкі бойынша виджетіңізді кез келген веб-сайтқа кірістіруге болады. Мұны шектеу үшін виджет параметрлерінде "Allow all domains" ауыстырғышын қолданыңыз.

Нақты домендермен шектеу

Шектелген кезде рұқсат етілуі тиіс әр доменді қосыңыз:

Домен атауларын https:// жоқ енгізіңіз (мысалы, example.com)
Субдомендерге бөлек жазбалар қажет (мысалы, www.example.com, shop.example.com)
Порттарды көрсетуге болады (мысалы, localhost:3000)
Ең көбі 50 домен ақ тізімге енгізуге болады

Қауіпсіздік

Өндірістік агенттер үшін рұқсатсыз кірістіруді болдырмас үшін виджеттерді өз домендеріңізбен шектеңіз.

Terms & Conditions

Қоңырау шалушылар сөйлесуді бастамас бұрын келісім диалогын қосыңыз.

Конфигурация

Параметр	Сипаттама
Enable Terms	Terms диалогын қосу/өшіру
Terms Content	Пайдаланушыларға көрсетілетін Markdown пішіміндегі келісім мәтіні (ең көбі 5,000 таңба)
Terms URL	Толық Terms & Conditions бетіне сілтеме
Privacy URL	Privacy Policy бетіне сілтеме

Қосылған кезде:

Пайдаланушылар қоңырауды бастамас бұрын келісім диалогын көреді
Жалғастыру үшін олар "Agree" батырмасын басуы керек
Келісім браузерде жергілікті сақталады
Reset Consent батырмасы сынау үшін сақталған келісімді тазалайды

Мазмұнды пішімдеу

Terms мазмұны Markdown пішімдеуін қолдайды:

Тақырыптар үшін #### қолданыңыз
Ерекшелеу үшін **bold** қолданыңыз
Оқуға ыңғайлылық үшін жол ауыстыруларды қолданыңыз

Қатысты

Callback Widget — Браузерде сөйлескісі келмейтін келушілерге арналған телефон кері қоңыраулары
Дауыстық агенттерге шолу
Параметрлер — Виджет конфигурациясын қоса, агент параметрлері
Интеграциялар — API кілттері және телефон нөмірін орнату

Сайт виджеттері

Виджет түрлері

Ортақ атрибуттар

Дисплей атрибуттары

Батырма мәтіні атрибуттары

Terms атрибуттары

Дыбыс атрибуттары

Түс тақырыптары

Кірістіру мысалдары

Floating Widget

Тақырыбы мен орны бар Floating Widget

Pill Widget

Inline Widget

Виджет оқиғалары

Мысал: Оқиғаларды тыңдау

Агентке беттерді ашуға рұқсат беру

1-қадам — Агентке қандай беттер бар екенін айтыңыз

2-қадам — Сұрауды өз бетіңізде өңдеңіз

3-қадам — Тексеріңіз

Агентке деректермен жауап беру

Агент нені сұрай алады, нені сұрай алмайды

Техникалық талаптар

Домен шектеулері

Әрдайым рұқсат етілген домендер

Барлық домендерге рұқсат ету

Нақты домендермен шектеу

Terms & Conditions

Конфигурация

Мазмұнды пішімдеу

Қатысты

Виджет түрлері​

Ортақ атрибуттар​

Дисплей атрибуттары​

Батырма мәтіні атрибуттары​

Terms атрибуттары​

Дыбыс атрибуттары​

Түс тақырыптары​

Кірістіру мысалдары​

Floating Widget​

Тақырыбы мен орны бар Floating Widget​

Pill Widget​

Inline Widget​

Виджет оқиғалары​

Мысал: Оқиғаларды тыңдау​

Агентке беттерді ашуға рұқсат беру​

1-қадам — Агентке қандай беттер бар екенін айтыңыз​

2-қадам — Сұрауды өз бетіңізде өңдеңіз​

3-қадам — Тексеріңіз​

Агентке деректермен жауап беру​

Агент нені сұрай алады, нені сұрай алмайды​

Техникалық талаптар​

Домен шектеулері​

Әрдайым рұқсат етілген домендер​

Барлық домендерге рұқсат ету​

Нақты домендермен шектеу​

Terms & Conditions​

Конфигурация​

Мазмұнды пішімдеу​

Қатысты​

Виджет түрлері

Ортақ атрибуттар

Дисплей атрибуттары

Батырма мәтіні атрибуттары

Terms атрибуттары

Дыбыс атрибуттары

Түс тақырыптары

Кірістіру мысалдары

Floating Widget

Тақырыбы мен орны бар Floating Widget

Pill Widget

Inline Widget

Виджет оқиғалары

Мысал: Оқиғаларды тыңдау

Агентке беттерді ашуға рұқсат беру

1-қадам — Агентке қандай беттер бар екенін айтыңыз

2-қадам — Сұрауды өз бетіңізде өңдеңіз

3-қадам — Тексеріңіз

Агентке деректермен жауап беру

Агент нені сұрай алады, нені сұрай алмайды

Техникалық талаптар

Домен шектеулері

Әрдайым рұқсат етілген домендер

Барлық домендерге рұқсат ету

Нақты домендермен шектеу

Terms & Conditions

Конфигурация

Мазмұнды пішімдеу

Қатысты