Технологиялар

Бір сұраумен қоңырау науқаны: AutoCall.kz API қалай жұмыс істейді

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

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

AutoCall.kz жүйесінде бұл бір POST. Біз бір нәрсені қысқартқандықтан емес, сұрау өрістері идентификаторлардан басқа мәндерді де қабылдайтындықтан. Мұның қалай жасалғанын және интеграторлар жиі сүрінетін API тұстарын қарастырайық.

Төрт сұраудың орнына біреу

POST
/api/v1/autocalls
POST /api/v1/autocalls
Authorization: Bearer {ваш_токен}
Content-Type: application/json

{
 "name": "Напоминание о приёме",
 "type": "regular",
 "time_from": "10:00:00",
 "time_to": "20:00:00",

 // аудио: дәл осы жерде синтездейміз, файл әлі жоқ
 "audio_id": [{
  "type": "synthesis",
  "data": { "text": "Здравствуйте! Напоминаем о приёме завтра." }
 }],

 // тізім: бұл да осында, алдын ала жасаудың қажеті жоқ
 "list_id": [
  { "number": "+77010000001", "variables": { "name": "Иван", "time": "14:30" } },
  { "number": "+77010000002", "variables": { "name": "Пётр", "time": "16:00" } }
 ],

 "sms_unanswered": true,
 "text_unanswered": "{{ name }}, не дозвонились. Ждём вас в {{ time }}."
}
Әдетте
  1. Тізім жасау
  2. Оған нөмірлерді жүктеу
  3. Аудиожазба жасау
  4. Өңделуін күту
  5. Қоңырау науқанын іске қосу
Бізде
  • Бір POST
  • Жауапта дайын қоңырау науқаны
  • Қадамдар арасында күйді сақтаудың қажеті жоқ
  • Ортасында құлайтын ештеңе жоқ

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

Өріс неге массив және оның ішінде неге объектілер болады

Біздің API туралы алдымен таң қалдыратыны: audio_id және list_id массивтер, оның үстіне әртүрлі элементтерден тұрады. Ретімен талдайық.

Массив, өйткені жазбалар бірнешеу болуы мүмкін

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

list_id өрісінде де солай: науқан бірнеше тізім бойынша бірден жүре алады. Тізімдер арасындағы қайталанатын нөмірлер біріктіріледі: адам «Алматы клиенттері» тізімінде де, «қарыздарлар» тізімінде де болса, бір ғана қоңырау алады.

Объект, өйткені нысан әлі болмауы мүмкін

Ал мұнысы қызықтырақ. Массив элементі не бар жазбаның ID нөмірі, не нені жасау керектігін сипаттайтын объект бола алады.

Өріс Нені беруге болады
audio_id [5, 7] — дайын жазбалардың ID нөмірлері
[{"type":"synthesis","data":{"text":"..."}}] — мәтіннен синтез
[{"type":"upload","data":{"file":"base64..."}}] — файлды жүктеу
[5, {"type":"synthesis", ...}] — екеуі аралас
list_id [10, 15] — дайын тізімдердің ID нөмірлері
[{"number":"+7701..."}] — нөмірлерді тікелей беру
[{"number":"+7701...","variables":{"name":"Иван"}}] — айнымалылармен

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

Практикалық әсері: бір реттік қоңырау науқанына сіздің базаңызда нысандар қажет емес. Біздің list_id мәнін өзіңізде сақтап, оның өзектілігін қадағалап, ескі тізімдерді тазалаудың қажеті жоқ. Нөмірлерді жібердіңіз, қоңырау науқанын алдыңыз.

Ал бір базамен жүйелі түрде жұмыс істесеңіз, тізімді POST /api/v1/lists арқылы бір рет жасап, кейін оның ID нөмірін беріп отырыңыз. Сонда контактілер науқаннан науқанға тіркелгіңізде қайталанбайды. Екі тәсіл де жұмыс істейді, таңдау сізде, API ештеңені мәжбүрлемейді.

Айнымалылар туралы

Контактідегі variables өрісі жеке мәтіндерге арналған алмастырулар. Олар SMS хабарламаларында (text, text_unanswered) және ЖИ-агент сценарийінде жұмыс істейді.

Күтпеген жағдай болмас үшін маңызды ескерту: кәдімгі қоңырау науқанының синтезделген аудиосына айнымалылар қойылмайды. Бүкіл науқанға бір аудиожазба, әйтпесе әр абонентке жеке файл жасауға тура келер еді. Шынымен жеке дауыс керек болса, интерактивті сценарийді немесе ЖИ-агентті пайдаланыңыз.

Өрістер неге «кейде» міндетті

Оңай сүрінетін екінші жер: өрістің міндеттілігі басқа өрістің мәніне байланысты. POST /autocalls сұрауында бұл былай көрінеді:

Егер берсеңіз Міндетті болады Себебі
"type": "regular" audio_id Кәдімгі науқан жазбаны ойнатады, онсыз қоңырау шалатын ештеңе жоқ
"type": "interactive" scenario_id Әңгімені сценарий басқарады
"type": "agent" agent_id Әңгімені ЖИ-агент жүргізеді
"sms": true text Мәтінсіз SMS жіберуге болмайды
"sms_unanswered": true text_unanswered Жауап бермегендер үшін де солай
time_from time_to Керісінше де солай: терезе шекаралары тек жұппен беріледі

Солай болуы керек. Баламасы — денелері бір-біріне ұқсас үш бөлек эндпоинт: /autocalls/regular, /autocalls/interactive, /autocalls/agent, ал сіздің кодыңыз олардың ортақ бөлігін түгел қайталайды: кесте, әрекеттер, SMS, callback_url. Науқан түрі — науқанның қасиеті, бөлек ресурс емес.

Өріс келмесе, жауап қайсысы және неге екенін тура айтады.

422
Unprocessable Entity
← 422 Unprocessable Entity

{
 "message": "The given data was invalid.",
 "errors": {
  "audio_id": ["Поле audio id обязательно, когда type равно regular."]
 }
}

HTTP мәртебесі — нақты статустың өзі

Мұны бөлек айту керек, себебі ол қалғанының бәрінен көп интеграцияны бұзады.

Біздің API жауабының негізгі бөлігінде "status": "ok" өрісі жоқ. Операцияның нәтижесі — HTTP коды. Ол дәл осы үшін ойлап табылған.

Код Не болды Не істеу керек
201 Науқан жасалды, қаражат резервке қойылды Жауап денесіндегі id мәнін сақтаңыз
202 Өңдеуге қабылданды. Алушылар соншалықты көп болғандықтан, сервис оларды жөнелтімдерге фондық режимде бөледі, мұны HTTP сұрауының ішінде күту дұрыс емес Бұл да сәтті нәтиже. Нәтижені кейін id бойынша GET арқылы алыңыз
402 Резервке қоюға баланс жетпеді Толықтырып, қайталаңыз. «Сол күйінде» қайталаудың пайдасы жоқ
422 Валидациядан өтпеді errors өрісін қарап, сұрауды түзетіңіз. Қайталау көмектеспейді
429 Минутына 300-ден астам сұрау Күтіп, қайталаңыз, мұны қайталауға болады

«Қайталауға болады» мен «қайталаудың пайдасы жоқ» арасындағы айырмашылық — бұл кодтардың бар болуының жалғыз себебі. Сервис кез келген жағдайға {"status":"error"} денесімен 200 OK деп жауап берсе, бұл айырмашылық жоғалады: HTTP клиентіңіз сұрауды сәтті деп санайды, қайталау саясаты іске қосылмайды, мониторинг жасыл графиктерді көрсетеді, ал науқан жіберілмеген.

Интеграциядағы ең жиі қате былай көрінеді: клиент жауапта id бар-жоғын ғана тексеріп, 402 кодын үнсіз елемейді. Науқан «жіберілген», логтар таза, қоңыраулар жоқ. Дененің пішінін емес, жауап кодын тексеріңіз.

Біздің ID сақтамай, науқаныңызды қалай табуға болады

Жасау кезінде client_id өрісін, яғни науқанның өз идентификаторыңызды беруге болады:

GET
/api/v1/autocalls?client_id=
POST /api/v1/autocalls // { ..., "client_id": "campaign-2026-07-31" }

GET /api/v1/autocalls?client_id=campaign-2026-07-31
← 200 OK // сол науқанның өзі, барлық қоңыраулары мен есептегіштерімен

Науқандарды өзіңіз нөмірлейтін болсаңыз және бөгде ID үшін артық баған қосқыңыз келмесе, ыңғайлы. /bulks және /scenarios ішінде де дәл солай жұмыс істейді.

Бұл іздеуге арналған кілт, қайталанудан қорғаныс емес. Бірдей client_id бар екі POST екі науқан жасап, қаражатты екі рет резервке қояды. Қайталаулардың идемпотенттілігі бұрынғыдай сіздің жағыңызда.

Соңында REST туралы аздап ұсақ-түйек

API туралы сөз болып жатқандықтан, тым ұсақ болып көрінетін, бірақ уақыт үнемдейтін бірнеше шешімді айта кетейік.

Жасау — бұл POST, GET емес. Теорияның тазалығы үшін емес. Спецификация бойынша GET қауіпсіз әрі қайталана береді, айналадағының бәрі соған сүйенеді: браузерлер мен прокси мұндай жауаптарды кэштейді, іздеу роботтары сілтемелер бойынша өздері жүреді, логтар мен тарих URL мекенжайын толық жазады. Науқанды GET арқылы жасау науқанның «Жаңарту» батырмасынан қайта кетуі мүмкін екенін, ал абоненттердің нөмірлері веб-сервер логына ашық мәтінмен түсетінін білдіреді.

Ресурстар көпше түрде. /autocalls, /autocall емес. Жинақ — бұл көптік: /autocalls — барлық науқандар, /autocalls/42 — қырық екінші науқан. Ереже жалықтыратын, есесіне кез келген эндпоинтті құжаттаманы бір рет те ашпай-ақ болжауға болады.

Сұрау денесі — JSON, query параметрлері емес. URL ұзындығы шектеулі, query ішінде кірістірілген құрылымдар жоқ, ал мекенжай жолындағы абонент нөмірлері мен хабарлама мәтіндері сұрау өтетін әр логқа ағып кетеді.

Әрі қарай

Толық сипаттама openapi.yaml файлында: оны Postman, Insomnia немесе клиент генераторына беріп, ештеңені қолмен қайта жазбай-ақ өз тіліңізде дайын SDK алуға болады. Мысалдары бар шолу беті: API және интеграциялар.

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

Бір сұрау жіберсеңіз, науқан басталады

Токен алып, алғашқы науқаныңызды кодтан іске қосыңыз.

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