Вебхуктар және жеткізу

Әр қоңыраудан кейін Hanc.AI қоңырауды — түйіндемені, транскриптті, шығарып алынған өрістерді — өз жүйеңізге жібере алады: тикет жүйесіне, CRM-ге, ERP-ге немесе кез келген HTTPS эндпоинтіне. Бұл бетте осы жеткізудің нақты қалай жұмыс істейтіні сипатталған: серверіңіз қолжетімсіз болғанда не болатыны, біз қанша рет қайталайтынымыз, брандмауэріңіз нені өткізуі керек екені және сұраудың қандай болатыны.

Барлық тарифтер

Қоңыраудан кейінгі жеткізу, қайталаулар мен жеткізу журналы кез келген тарифте, соның ішінде Free тарифінде қолжетімді.

Не жіберіледі және қашан

Сұрау қоңырау аяқталып, оның талдауы біткен бойда (түйіндеме, көңіл-күй, сіздің шығарып алынған өрістеріңіз) жіберіледі — әдетте тұтқа қойылғаннан кейін бірнеше секундтан соң.

Дереккөз	Қай жерде бапталады
«API қоңырауы» әрекеті	Агент → Әрекеттер → Post call → API қоңырауы
Жұмыс ағынының қадамы	Жұмыс ағыны құрастырғышы → Қашан орындалады: Қоңыраудан кейін мәні бар API шақыруы құрал қадамы
Агент вебхугы	Агенттің `webhook_url` өрісі (API анықтамасы)

Агент сөйлесу барысында жасайтын сұраулар (жанды құралдар) мұнда қарастырылмайды: олар дәл сол сәтте қажет және кейін ешқашан қайталанбайды.

Серверіңіз қолжетімсіз болғанда

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

Эндпоинтіңіз 30 секунд ішінде кез келген 2xx күйімен жауап берсе, жеткізу сәтті деп саналады.
Қалғанының бәрі қайталанады: қосылымнан бас тарту, DNS немесе TLS қателері, күту уақытының аяқталуы және кез келген басқа күй — 5xx, 429, сондай-ақ 4xx. Егер API кілтінің мерзімі өтіп, оны жаңартсаңыз, күтіп тұрған қоңыраулар өздігінен жетеді.
Әр талпыныста сол бір жеткізу идентификаторы бар сол сұраудың өзі жіберіледі.

Қайталау кестесі

Талпыныс	Оның алдындағы үзіліс	Қоңырау аяқталғаннан бергі уақыт
1	— (бірден)	~0
2	1 минут	~1 мин
3	5 минут	~6 мин
4	30 минут	~36 мин
5	2 сағат	~2 сағ 36 мин
6	6 сағат	~8 сағ 36 мин
7	24 сағат	~1 күн 8 сағ
8	48 сағат	~3 күн 8 сағ

Барлығы шамамен 3,4 күн ішінде 8 талпыныс — бұл демалыс күндеріндегі іркілісті де жабуға жеткілікті.

Өз кестеңіз

API қоңырауы әрекетінде (және қоңыраудан кейін орындалатын жұмыс ағынының API шақыруы қадамында) кестені Қате кезіндегі қайталаулар бөлімінде ауыстыра аласыз:

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

Сіз ешқашан өзгертпеген әрекет жоғарыдағы стандартты кестемен жұмыс істейді.

Соңғы талпыныстан кейін

Жеткізу Жеткізілмеді деп белгіленеді, сізге электрондық пошта арқылы хабарланады (егер мұны өшіріп қоймасаңыз), ал сұрау 30 күн сақталады. Осы уақыт ішінде оны қайта жібере аласыз — жеткізу журналында бір рет басу немесе бір API сұрауы жеткілікті. Сәтті аяқталған жеткізуді де қайта жіберуге болады, мысалы, сіздің тарапыңызда деректер қалпына келтірілгеннен кейін.

Кез келген вебхукқа тәуелсіз, қоңыраудың өзі Hanc.AI аккаунтыңызда қалады — транскрипт, түйіндеме, аудиожазба және шығарып алынған өрістер Қоңыраулар бөлімінде және API арқылы қолжетімді. Ұзақ іркіліс деректерді жүйеңізге беруді кешіктіреді, бірақ сөйлесуді жоймайды.

Кемінде бір рет

Жеткізу кемінде бір рет орындалады. Сирек жағдайларда — мысалы, серверіңіз сұрауды өңдеп, бірақ жауап бізге уақытында жетпегенде — сол бір қоңырау екі рет келеді. Қайталанған сұрауды танып, өткізіп жіберу үшін X-Hanc-Delivery-Id мәнін пайдаланыңыз.

Сәтсіздік туралы хабарламалар

Журналды бақылап отырудың қажеті жоқ: сұрауы жеткізілмеген кезде әрекет сізге электрондық пошта арқылы хабарлай алады. Әрекеттегі (немесе жұмыс ағыны қадамындағы) Сәтсіздік туралы хабарлама бөлімінде таңдаңыз:

Параметр	Хат қашан жіберіледі
Соңғы әрекеттен кейін (әдепкі)	Бір рет — қайталау кестесі таусылып, сұрау Жеткізілмеді деп белгіленгенде
Әр сәтсіз әрекеттен кейін	Әр сәтсіз талпыныстан кейін, келесісінің уақыты көрсетіліп — және соңғысынан кейін
Хабарламау	Ешқашан; сәтсіздіктер тек журналда көрінеді

Хатта әрекет пен агенттің атауы, серверіңіздің хосты, оның жауабы (мысалы, HTTP 503 немесе timeout after 30s), барлық талпыныстың нешіншісі екені көрсетіледі және жеткізу журналына сілтеме беріледі. Соңғы хатта сұраудың қашанға дейін сақталатыны және оны қайта жіберуге болатыны да айтылады.

Кімге жіберу өрісі алушыны белгілейді — әдетте бұл қабылдаушы жүйені басқаратын адам. Өріс бос қалса, хат аккаунт иесіне жіберіледі. Хат аккаунт тілінде жазылады.

Іркіліс кезінде пошта жәшігіңіз хаттарға толып кетпеуі үшін хабарламалар әр әрекет бойынша сағатына 10 және тәулігіне 30 хатпен шектеледі; үзіліс алдындағы соңғы хатта оның қашанға дейін созылатыны көрсетіледі. Әр сәтсіздік бұрынғыдай журналға жазылады. Қолмен қайта жіберілген сұрау туралы хабарлама жіберілмейді.

Жеткізу журналы

Әр талпыныс тіркеледі: уақыты, HTTP күйі немесе желі қатесі, ұзақтығы және серверіңіз жауабының басы.

Қолданбада: CRM → Коммуникациялар → API шақыруы түріндегі жазбаны ашыңыз. Онда күйді (Жеткізілді, Қайталануда, Жеткізілмеді), барлық талпынысты, келесісінің уақытын және Қайта жіберу түймесін көресіз.

API арқылы (аутентификация — x-api-key тақырыбындағы API кілтіңізбен):

Сұрау	Нәтиже
`GET /v1/webhook-deliveries`	Жеткізулеріңіз, жаңасынан бастап. Сүзгілер: `status` (`pending`, `delivered`, `failed`), `agent_id`, `call_id`, `limit`, `offset`
`GET /v1/webhook-deliveries/{id}`	Барлық талпынысы мен сұрау денесі бар бір жеткізу
`POST /v1/webhook-deliveries/{id}/resend`	Оны дәл қазір қайта жібереді және нәтижесін қайтарады

{
  "id": "6ac71fb82e4f72e709a4a566",
  "delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
  "kind": "api_call",
  "name": "Create ticket",
  "call_id": "6ac71f9d2e4f72e709a4a4f0",
  "status": "pending",
  "attempts_made": 2,
  "attempts_max": 8,
  "next_attempt_at": "2026-10-09T11:36:04.000Z",
  "attempts": [
    { "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
    { "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
  ]
}

Сақталған сұраудың тақырып мәндері (сіздің кілттеріңіз) ешқашан қайтарылмайды.

Желі және брандмауэр

Hanc.AI сіздің эндпоинтіңізді шақырады — қосылым әрқашан біздің тараптан сіздің тарапқа қарай ашылады.


Бағыт	Hanc.AI тарапынан шығыс → сіздің тарапыңызда кіріс
Жіберуші IP мекенжайлары	`178.104.10.47` (жеткізу қызметі) және `128.140.65.92` (қоңырау қызметі, резервтік жол ретінде қолданылады)
Протокол	HTTPS (TLS 1.2 немесе одан жаңа). Шифрланбаған HTTP жұмыс істейді, бірақ ұсынылмайды
Порт	`443` немесе URL мекенжайыңызда көрсетілген порт
IP нұсқасы	IPv4
Сертификат	Жарамды және жария сертификаттау орталығы берген болуы керек; өзі қол қойған сертификаттар қабылданбайды
Жауап уақыты	30 секунд ішінде жауап беріңіз — ең дұрысы, бірден растап, өңдеуді фондық режимде орындаңыз
Қайта бағыттаулар	Орындалады, ең көбі 5

Рұқсат тізімі: брандмауэріңіз немесе WAF жіберуші мекенжайы бойынша сүзсе, жоғарыдағы екі мекенжайға вебхук жолыңыз үшін рұқсат беріңіз. Бұл мекенжайлардың өзгеретіні туралы алдын ала хабарлаймыз.

Мүмкін емес: жеке желі ішіндегі мекенжайлар (10.x, 172.16–31.x, 192.168.x, localhost). Эндпоинт интернеттен қолжетімді болуы керек — тікелей немесе кері прокси / API шлюзіңіз арқылы.

Браузер: вебхуктар серверден серверге жұмыс істейді. Браузер параметрлері, кеңейтімдер немесе қызметкерлердің жұмыс компьютерлеріндегі ашық порттар мұнда қатыспайды.

Сұрау пішімі

POST, PUT және PATCH сұрауларында JSON денесі болады (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "call_summary": "Customer reports a broken router and asks for a callback…",
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "task_achieved": true,
  "sentiment": { "sentiment": "neutral", "explanation": "…" },
  "custom_analysis_data": {
    "customer_number": "K-20417",
    "ticket_category": "Hardware",
    "priority": "high"
  },
  "collected_data": { },
  "transfer_history": [ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup"
}

Өріс	Мазмұны
`call_summary`	Сөйлесудің түйіндемесі
`transcription`	Толық сөйлесу, реплика бойынша, уақыт белгілерімен
`call_from`, `call_to`, `direction`	Қоңырау шалушы, қоңырау шалынған нөмір, кіріс немесе шығыс
`start_timestamp`, `end_timestamp`, `duration`	Unix уақыты және миллисекундпен берілген ұзақтық
`custom_analysis_data`	Сөйлесуден шығарып алынған өз өрістеріңіз — Шығарып алу айнымалылары бөлімін қараңыз
`collected_data`	Агент қоңырау кезінде жинаған деректер
`sentiment`, `task_achieved`	Сөйлесудің көңіл-күйі және оның мақсатына қол жеткізілген-жеткізілмегені
`recording_url`	Жазу қосулы болса, аудиожазбаға сілтеме
`transfer_history`	Қоңырау барысында жасалған аударулар

GET және DELETE үшін сол өрістер сұрау жолында (query string) беріледі; transcription сияқты кірістірілген мәндер қосылмайды.

Тақырыптар

Тақырып	Мағынасы
`X-Hanc-Delivery-Id`	Жеткізуді сәйкестендіреді. Әр талпыныста бірдей — қайталанған сұрауларды өткізіп жіберу үшін пайдаланыңыз
`X-Hanc-Attempt`	Талпыныс нөмірі, `1`-ден басталады
`X-Correlation-Id`	Ішкі бақылау идентификаторы; қолдау қызметіне жүгінгенде оны көрсетіңіз
`User-Agent`	`HANC-Webhooks/1.0`
өз тақырыптарыңыз	Әрекетте баптағаныңыздың бәрі

Аутентификация

Эндпоинтіңіз бізді қалай танитынын өзіңіз шешесіз:

API кілті немесе токен — әрекетке тақырып қосыңыз, мысалы, Authorization: Bearer <token> немесе X-API-Key: <key>. Тақырыптар әр талпыныста жіберіледі.
Basic auth — Authorization: Basic <base64(user:password)>.
Query параметрі — кілтті URL ішінде күтетін жүйелер үшін.
Жіберуші мекенжайы — тек жоғарыда көрсетілген IP мекенжайларына рұқсат беріңіз.

Бұл тәсілдерді біріктіруге болады; әдетте кілт пен IP рұқсат тізімі бірге қолданылады.

Сұрауды жүйеңізге бейімдеу

Әдепкі бойынша сұрауда бүкіл қоңырау болады (Сұрау пішімі бөлімін қараңыз). Өз құрылымын күтетін жүйе үшін — тикет жүйелерінің көбі осындай — сол құрылымды өзіңіз сипаттап, оны қоңырау деректерімен толтырасыз.

Айнымалылар

Қоңыраудан кейінгі API қоңырауы әрекетінде және жұмыс ағынының API шақыруы қадамында URL, тақырыптар, query параметрлері және дене қос фигуралы жақшадағы айнымалыларды қабылдайды. Олар сұрау жіберілер алдында қоңырау деректерінен толтырылады.

Айнымалы	Мәні
`{{call_id}}`	Қоңырау идентификаторы
`{{call_from}}`, `{{call_to}}`	Қоңырау шалушы және қоңырау шалынған нөмір
`{{customer_phone}}`, `{{customer_email}}`	Қоңырау бағытына қарамастан, екінші тараптың нөмірі мен электрондық поштасы
`{{call_direction}}`, `{{call_type}}`	`inbound` / `outbound`, `phone` / `web`
`{{call_start}}`, `{{call_end}}`	Басталуы мен аяқталуы, ISO 8601 (UTC)
`{{call_duration}}`	Секундпен берілген ұзақтық
`{{call_summary}}`	Сөйлесудің түйіндемесі
`{{call_transcription}}`	Мәтін түріндегі толық сөйлесу
`{{call_sentiment}}`, `{{call_task_achieved}}`	Көңіл-күй және мақсатқа қол жеткізілген-жеткізілмегені
`{{call_recording_url}}`	Аудиожазбаға сілтеме
`{{agent_id}}`	Агент идентификаторы
өз өрістеріңіз	Әр шығарып алу айнымалысы өз атауымен, мысалы, `{{customer_number}}`, `{{priority}}` — сондай-ақ жұмыс ағыны қоңырау кезінде жинаған әр айнымалы

Білген жөн ережелер:

Тек бір айнымалыдан тұратын дене өрісі сол айнымалының түрін сақтайды: "priority": "{{priority}}" 3 саны ретінде, ал "urgent": "{{urgent}}" true ретінде жіберіледі. Айнымалының айналасында мәтін болса, мән мәтінге айналады.
URL ішіне қойылған мән автоматты түрде пайыздық кодтаудан өтеді (+43… %2B43… болып өзгереді).
Қоңырауда мәні жоқ айнымалы бос күйінде жіберіледі — {{name}} жазуының өзі ешқашан жіберілмейді.

Қолданбада өрістегі {x} түймесі қолжетімді айнымалылардың тізімін көрсетеді; денеде {{ терсеңіз, олар ұсынылады.

Дене

Әрекеттегі Денесі (JSON) өрісіне жүйеңіз күтетін JSON нысанын жазасыз — кірістіру тереңдігі қажетінше бола береді:

{
  "ticket": {
    "subject": "Call from {{customer_phone}}: {{ticket_category}}",
    "comment": { "body": "{{call_summary}}" },
    "priority": "{{priority}}",
    "custom_fields": [
      { "id": 360001, "value": "{{customer_number}}" },
      { "id": 360002, "value": "{{call_recording_url}}" }
    ],
    "tags": ["phone-agent"]
  }
}

Тек өз өрістеріңіз

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

Таңдап жіберу

Қарапайым тілде жазылған шарт («тек қоңырау шалушы ақау туралы хабарласа») сұрауды қай қоңыраулар іске қосатынын анықтайды. Бірнеше әрекет әртүрлі жүйелерге немесе эндпоинттерге бағытталуы мүмкін.

Тикет жүйесін қосу

HTTP API-ді немесе кіріс вебхукты қолдайтын кез келген тикет жүйесі қоңырауларды қабылдай алады — тікелей, аралық бағдарламалық жасақтамасыз. Сіздің тарапыңызда мыналар қажет:

Интернеттен HTTPS арқылы қолжетімді және JSON қабылдайтын эндпоинт.
Оған арналған тіркелгі деректері (API кілті, токен немесе basic auth) — әрекетке тақырып ретінде енгізіледі.
Мекенжай бойынша сүзсеңіз — рұқсат тізіміңіздегі жоғарыда аталған екі IP мекенжайы.

Содан кейін әрекетте:

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

Жүйеңізге арналған денені сізбен бірге қуана дайындаймыз.

Тестілеу

Қосылымды тексеру. Әрекеттегі API конфигурациясын сынау түймесі үлгі сұрауды бірден жібереді және эндпоинтіңізге жеткен-жетпегенін көрсетеді.

Қайталауларды тексеру — механизмді өз көзіңізбен көру үшін:

Әрекетте Қате кезіндегі қайталаулар бөлімінде қысқа кесте орнатыңыз, мысалы, 1 минуттан үш үзіліс.
Эндпоинтіңізді тоқтатыңыз немесе брандмауэрде біздің мекенжайларды бұғаттаңыз.
Агентке сынақ қоңырауын шалыңыз.
CRM → Коммуникациялар бөлімін ашыңыз: жазбада Қайталануда күйі, сәтсіз талпыныс пен оның қатесі және келесі талпыныстың уақыты көрсетіледі.
Эндпоинтті қайта іске қосыңыз (немесе бұғатты алып тастаңыз). Келесі талпыныс қоңырауды жеткізеді де, жазба Жеткізілді күйіне ауысады — немесе бірден жеткізу үшін Қайта жіберу түймесін басыңыз.

Эндпоинтіңізге арналған тексеру тізімі

Сұрау сақталған бойда 2xx күйімен жауап беріңіз; ауыр жұмысты содан кейін орындаңыз.
X-Hanc-Delivery-Id мәнін идемпотенттілік кілті ретінде қолданыңыз.
Сұрауды қабылдай алмаған жағдайда 4xx/5xx күйімен жауап беріңіз — біз қайта ораламыз.
Сертификаттың жарамдылығын және екі жіберуші мекенжайына берілген рұқсатты сақтаңыз.

Не жіберіледі және қашан​

Серверіңіз қолжетімсіз болғанда​

Қайталау кестесі​

Өз кестеңіз​

Соңғы талпыныстан кейін​

Сәтсіздік туралы хабарламалар​

Жеткізу журналы​

Желі және брандмауэр​

Сұрау пішімі​

Тақырыптар​

Аутентификация​

Сұрауды жүйеңізге бейімдеу​

Айнымалылар​

Дене​

Тек өз өрістеріңіз​

Таңдап жіберу​

Тикет жүйесін қосу​

Тестілеу​

Эндпоинтіңізге арналған тексеру тізімі​