Интеграциялар

Сатып алуды аяқтамаған клиентке ЖИ-агентпен хабарласу

← Барлық мақалалар

Клиент дүкенге кіріп, себетіне тауар салды, «Рәсімдеу» батырмасын басты. Төлемге келгенде тоқтап қалды. Жиі болатын жағдай: басқа шаруасы шығып кетті, күмәнданды, картадан төлем өтпеді немесе «кешке қараймын» деп ұмытып кетті. Ол бір минут бұрын тауарды алғысы келіп, сатып алуға сәл-ақ қалған адам.

Әдетте клиентке «Себетіңізде тауар қалып қойды» деген хат жіберіледі. Оны ашатындар аз, хатты оқып дүкенге қайта кіретіндер одан да аз. Ал клиент дүкеннен шыққан соң он минуттан кейін телефон шырылдаса ше? «Сәлеметсіз бе! Біздің дүкенде себетіңізге тауар салған едіңіз. Бәрі дұрыс па? Тапсырысты рәсімдеуге бірдеңе кедергі болды ма?» Мұндай қоңырауға адамдар басқаша жауап береді.

Осы интеграцияны басынан аяғына дейін құрастырамыз. Дауыстық ЖИ-агент қоңырау кезінде себетте не барын жүйеңізден API арқылы өзі алады, клиентпен сөйлесіп, нәтижесін Telegram арқылы менеджерлерге жібереді. Кодтың бәрі төменде. Бір кеште қайталап жасауға болады.

Нәтижесінде не аламыз

1
Дүкен сатып алу аяқталмағанын байқап, бір сұрау арқылы AutoCall.kz жүйесінде қоңырауды іске қосады
↓
2
ЖИ-агент клиентке қоңырау шалады да, әңгіменің басында дүкеніңіздің GET /cart әдісін нөмір бойынша шақырып, себетте не барын біледі
↓
3
Әңгіме: агент тапсырыстың неге рәсімделмегенін анықтайды, көмектеседі, клиент қаласа, төлем сілтемесі бар SMS жібереді
↓
4
Қорытынды сіздің callback_url мекенжайыңызға келеді, ал одан менеджерлердің Telegram тобына ұқыпты карточка болып түседі

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

1-қадам. Агентті бір рет жасаймыз

Агент бір рет жасалады, кейін барлық қоңырауға қызмет етеді. Оның үш бөлігі бар: әңгіме сценарийі (prompt), ол толтыруға тиіс өрістер (data_schema) және құралдар (tools): себетті сұрау мен SMS жіберу.

POST
/api/v1/agents
POST https://autocall.kz/api/v1/agents Authorization: Bearer {ваш_токен} Content-Type: application/json { "name": "Аружан", "voice": "Sulafat", // дауыстар: GET /api/v1/agents/voices "max_seconds": 180, "client_id": "cart-recovery", "prompt": "## Кто ты\nАружан — женский голос интернет-магазина «SHOP». Звонишь клиенту,\nкоторый собрал корзину и начал оформление, но не оплатил. Характер:\nдоброжелательная, лёгкая, без давления. Ты помощник, а не продавец.\n\n## Задача звонка\nПонять, почему заказ не завершён, и помочь довести до конца, если человек\nэтого хочет. Не хочет — вежливо попрощаться и не давить.\n\n## Ход разговора\n1. Первая фраза РОВНО: «Здравствуйте! Это Аружан из магазина SHOP.\n Вы недавно собирали у нас корзину — удобно сейчас говорить?»\n2. Сразу после приветствия узнай состав корзины через инструмент.\n3. Назови, что в корзине, и мягко спроси, всё ли в порядке, не помешало\n ли что-то оформить.\n4. Техническая проблема (не прошла оплата, вопрос по доставке) — предложи\n помощь; если клиент готов вернуться, отправь ссылку на оплату.\n5. Передумал или просто смотрел — спокойно прими, поблагодари, попрощайся.\n\n## Границы\nНе дави и не уговаривай после отказа. Скидок, которых нет, не обещай.\nО товаре и цене говори только то, что вернул инструмент.", "data_schema": [ { "key": "outcome", "label": "Итог" }, // рәсімдеуге дайын / райынан қайтты / көмек керек / қайта қоңырау шалу { "key": "reason", "label": "Причина" }, // рәсімдеуді неге аяқтамады { "key": "comment", "label": "Комментарий" } ], "tools": [ { "type": "http", "name": "order", // агент мұны call_order функциясы ретінде шақырады "when": "сразу после приветствия, чтобы узнать состав корзины", "method": "GET", "url": "https://shop.kz/api/cart?phone={{phone}}", "headers": [{ "key": "Authorization", "value": "Bearer SHOP_TOKEN" }], "response_template": "В корзине: {{items}} на сумму {{total}} тенге.", "fallback": "Заказ поднять не удалось, но давайте разберёмся вместе." }, { "type": "sms", "name": "link", // send_sms_link функциясы "when": "если клиент готов вернуться к оформлению", "text": "Ваша корзина ждёт вас: https://shop.kz/cart" } ] }

Бірнеше нәрсені нақтылап алайық.

Промпт бөлімдері міндетті. ## Кто ты (сен кімсің), ## Задача звонка (қоңырау мақсаты) және ## Ход разговора (әңгіме барысы) болуы керек, оларсыз агентті жасау сұрауы 422 қайтарады. Қауіпсіздік ережелерін өзіміз қосамыз, оларды промптқа жазудың қажеті жоқ.

order құралы — дәл осы интеграцияның өзі. Қоңырау кезінде агент оны функция ретінде шақырады, ал біз URL ішіне {{phone}} мәнін, яғни клиенттің нөмірін қойып, дүкеніңізге GET сұрауын жібереміз. Серверіңіз не қайтарса, агент оны response_template үлгісі бойынша айтады. Мәндерді қою туралы толығырақ сәл төменде.

Жауап generating мәртебесімен келеді. Агент бірден дайын болмайды: оның параметрлерін есептеуге бірер секунд кетеді. GET /api/v1/agents/{id} арқылы тексеріп отырып, ready мәртебесін күтіңіз және id мәнін сақтап алыңыз: ол қоңырауларды іске қосқанда керек болады.

2-қадам. Дүкеніңіз себетті нөмір бойынша береді

Бұл сіздің жағыңызда іске қосу керек жалғыз эндпоинт. Агент оны қоңырау кезінде шақырады. Жауап пішімін өзіңіз анықтайсыз, тек өріс атаулары агенттің response_template үлгісіндегі атаулармен ({{items}} және {{total}}) сәйкес келуі маңызды.

GET
сіздің дүкен · /api/cart
GET https://shop.kz/api/cart?phone=77010000000 ← 200 OK { "items": "робот-пылесос Samsung и набор насадок", "total": "45 000" }

Біз осы JSON жауабын аламыз, items мен total мәндерін үлгіге қоямыз, ал агент былай дейді: «Себетте: Samsung робот-шаңсорғышы мен саптамалар жиынтығы, жалпы сомасы 45 000 теңге». Серверіңіз жауап бермесе немесе басқа нәрсе қайтарса, агент fallback мәтінін айтып, әңгімені жалғастырады, қоңырау үзілмейді.

Эндпоинт ашық интернетке шығады, сондықтан оны токенмен жабыңыз (біз құрал баптауларындағы Authorization тақырыбын жібереміз) және нөмір бойынша тек себет құрамын беріңіз: мекенжайларсыз, карталарсыз және басқа артық деректерсіз.

3-қадам. Аяқталмаған тапсырысты анықтап, қоңырау шаламыз

Енді дүкен жағы. Жүйеңіз себетті тасталды деп шешкенде (мысалы, төлем қадамынан кейін 10 минут өтіп, төлем болмаса), бір сұрау қоңырауды іске қосады.

Python
shop_backend.py
import requests AUTOCALL_TOKEN = "autocall_токеніңіз" AGENT_ID = 42 # 1-қадамдағы дайын агенттің идентификаторы def call_about_cart(phone: str, name: str): requests.post( "https://autocall.kz/api/v1/autocalls", headers={"Authorization": f"Bearer {AUTOCALL_TOKEN}"}, json={ "name": "Возврат корзины", "type": "agent", "agent_id": AGENT_ID, "time_from": "10:00:00", # тек қолайлы сағаттарда қоңырау шаламыз "time_to": "20:00:00", "max_tries": 1, # бір ғана қоңырау, мазаламаймыз "callback_url": "https://your-service.kz/autocall/callback", "list_id": [ { "number": phone, "variables": {"phone": phone.lstrip("+"), "name": name} } ] } )

Бар мәселе variables өрісінде. Агент себетті сұрағанда, құралдың URL мекенжайындағы {{phone}} орнына дәл осы жердегі phone кілті қойылады. Айнымалыларға не салсаңыз, құрал соны пайдалана алады.

Бэкендіңіз Python тілінде болмаса, сол сұрау curl арқылы:

cURL
қоңырауды іске қосу
curl -X POST https://autocall.kz/api/v1/autocalls \ -H "Authorization: Bearer токеніңіз" \ -H "Content-Type: application/json" \ -d '{ "name": "Возврат корзины", "type": "agent", "agent_id": 42, "time_from": "10:00:00", "time_to": "20:00:00", "max_tries": 1, "callback_url": "https://your-service.kz/autocall/callback", "list_id": [{ "number": "+77010000000", "variables": { "phone": "77010000000", "name": "Айгерим" } }] }'

4-қадам. Telegram ботын дайындаймыз

Бот қорытындыны менеджерлер тобына жазу үшін керек. Үш қысқа әрекет:

  1. @BotFather ботына /newbot командасын жазып, атау беріңіз. Жауап ретінде 7712345678:AAExxxxxxxxxxxx түріндегі токен аласыз.
  2. Ботты жұмыс тобыңызға қосып, хабар жазуға рұқсат беріңіз.
  3. Топтың chat_id мәнін біліңіз: оған уақытша @getidsbot ботын қосыңыз немесе https://api.telegram.org/bot{ТОКЕН}/getUpdates бетін ашыңыз. Топтың id мәні теріс сан болады.

5-қадам. Нәтижені қабылдап, Telegram тобына жазамыз

Біздің callback сұрауын қабылдап, оны хабарламаға айналдыратын шағын сервисті іске қосу ғана қалды. Біз callback_url мекенжайын қоңыраудың әр өзгерісінде шақырамыз, сондықтан алдымен әңгіменің соңын аралық оқиғалардан бөліп алу керек.

Әңгіме болғанының сенімді белгісі: status_tries массивінің соңғы элементі success мәніне тең. Сонда data ішінде агент жинаған өрістер тұрады.

Python
callback_service.py
from flask import Flask, request import requests app = Flask(__name__) BOT_TOKEN = "7712345678:AAExxxxxxxxxxxx" CHAT_ID = "-1001234567890" # менеджерлер тобының идентификаторы @app.post("/autocall/callback") def callback(): call = request.json.get("call", {}) tries = call.get("status_tries") or [] # қоңырау әлі жүріп жатыр немесе жауап болмады: соңын күтеміз, ештеңе жібермейміз if not tries or tries[-1] != "success": return "", 204 data = call.get("data") or {} text = ( "🛒 Недобитая корзина — итог звонка\n\n" f"📞 {call.get('number', '—')} · {call.get('duration', 0)} сек\n\n" f"Итог: {data.get('outcome', '—')}\n" f"Причина: {data.get('reason', '—')}\n" f"Комментарий: {data.get('comment', '—')}" ) requests.post( f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage", json={"chat_id": CHAT_ID, "text": text, "parse_mode": "HTML"} ) return "", 204

Ол HTTPS қолдайтын кез келген кері прокси артында кәдімгі Flask қосымшасы ретінде іске қосылады. /autocall/callback мекенжайы қоңырауды іске қосқанда callback_url өрісінде көрсеткен мекенжаймен дәл бірдей.

Нәтижені чатқа ғана емес, CRM жүйесіне де салғыңыз келсе, callback дәл осыған арналған. data ішінде data_schema өрістерінің бәрі және data["_transcript"], яғни әңгіменің толық мәтіні бар, егер ол сізге керек болса.

Қоңырауда бұл қалай естіледі

Тікелей сөйлесу
АружанСәлеметсіз бе! Бұл SHOP дүкенінен Аружан. Жақында бізде себет жинаған едіңіз, қазір сөйлесуге ыңғайлы ма?
КлиентӘ-ә, иә, не болды?
Аружан(call_order шақырады, дүкен жауап береді) Бір сәт, тапсырысыңызды қарайын… Көріп тұрмын: Samsung робот-шаңсорғышы мен саптамалар жиынтығы, 45 000. Бәрі дұрыс па, рәсімдеуге ештеңе кедергі болған жоқ па?
КлиентИә, алғым келген, бірақ карта неге екені белгісіз төлемді қабылдамады, сосын тастай салдым.
АружанТүсінемін, болып тұрады. Төлем сілтемесін SMS арқылы жібере аламын: басқа картамен немесе Kaspi арқылы төлеп көресіз, қалай ыңғайлы болса. Жіберейін бе?
КлиентИә, солай істейік.
Аружан(send_sms_link шақырады) Жібердім. Себетіңіз де сол жерде, бәрі сақталған. Уақыт бөлгеніңізге рақмет!

Осы сәтте менеджерлер топқа мынадай карточка алады:

🛒 Аяқталмаған себет: қоңырау қорытындысы
📞 +7 701 000 00 00 · 58 сек
Қорытынды: рәсімдеуге дайын, сілтеме жіберілді
Себебі: картамен төлем өтпеді
Түсініктеме: Kaspi арқылы төлеп көреді

Менеджерге жазбаны тыңдап, болжап отырудың қажеті жоқ: агент әңгімені өрістерге бөліп қойған. Кім шынымен сатып алғысы келіп, қай жерде тоқтап қалғаны, ал кім жай қарап жүргені көрініп тұр.

Назардан тыс қалдыруға болмайтын нюанстар

Адамға ыңғайлы уақытта бір-ақ рет қоңырау шалыңыз. Сұрауда max_tries: 1 және 10:00–20:00 аралығы бекер көрсетілмеген. Сатып алуға ниеті бар клиентке екінші рет немесе кешкі тоғызда қоңырау шалсаңыз, мазасын аласыз.

Тек success мәнін ғана қарамаңыз. Соңғы status_tries мәні no_answer немесе busy болса, әңгіме болмаған, data ішінде өрістер де болмайды. Мұндай оқиғаларды елемеуге болады, ал оларды пайдаланып әлгі «себетіңізді ұмытып кеттіңіз» хатын да жіберуге болады, енді ол қосалқы арна болады.

Нөмірін саналы түрде бермеген адамдарға қоңырау шалмаңыз. Бұл жерде бәрі таза: клиент тапсырысты рәсімдегенде телефонын өзі енгізіп, сатып алуды өзі бастады. Бұл сатып алынған база да, суық қоңырау да емес, сондықтан мұндай қоңырау жұмыс істейді және мазасыз көрінбейді. Бұл тәсілді сізден мұны сұрамаған аудиторияға қолданбаңыз.

Өзіңізге тексеріп көріңіз. Клиенттерге қоспас бұрын, тест себетпен өз нөміріңізге қоңырау жіберіңіз. Сондай-ақ агент карточкасындағы «Тексеру» батырмасы сізге браузерде қоңырау шалады, сонда алғашқы нақты қоңырауға дейін оның қалай сөйлейтінін тікелей естисіз.

Әрі қарай

Біз бір байламды құрастырдық, бірақ оның бөліктерін қайта қолдануға болады. Сол callback_url деректерді CRM жүйесіне салады, агенттің сол HTTP құралы себетті ғана емес, жүйеңіздегі кез келген деректі алады, ал қоңырауды іске қосуды кез келген оқиғаға байлауға болады: тасталған себетке ғана емес, «өтінім бір тәулік жауапсыз», «жазылым аяқталып жатыр», «тапсырыс жеткізілді» сияқты оқиғаларға да.

Әдістердің толық сипаттамасы openapi.yaml файлында, мысалдары бар шолу API және интеграциялар бетінде. Агенттің өзі қалай жұмыс істейтіні және оның сценарийден айырмашылығы туралы бөлек жаздық.

Өз интеграцияңызды құрастырыңыз

API токенін алып, алғашқы агентіңізді бүгін іске қосыңыз.

Тегін қолданып көру →