API арқылы қоңыраулар: командалар мен дауыс

Кілт желілеріндегі қоңыраулар

• GET /calls/ — қазір шырылдап немесе жүріп жатқан қоңыраулар, жаңалары алдымен (100-ге дейін).
• GET /calls/<id>/ — бір қоңырау.
• POST /calls/ — желіден 7–15 цифрлы нөмірге қоңырау шалу, мысал төменде.
• GET /operators/?channel_id=12 — қоңырауды бағыттауға болатын компания қызметкерлері.

curl -X POST https://dialogs.tehprof.kz/api/v1/gw/calls/ \
  -H "Authorization: Bearer gw_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "channel_id": 12, "number": "77001234567" }'

{ "id": 5310, "channel_id": 12, "direction": "out",
  "phase": "starting", "active": true, "yours": true, ... }

Қоңырауға командалар

transfer кейін клиент гудок естиді, желі адамдарында шырылдайды, бағдарламаның дауыс қосылымы жабылады.

Шығыс қоңырау берілгеннен кейін де шығыс болып қалады: direction — out, answered — true, phase қайтадан ringing.

Қоңырау өрістері

• id, channel_id, conversation_id, peer — клиенттің нөмірі немесе мессенджердегі id-і.
• direction — in немесе out; active — қоңырау әлі жүріп жатыр.
• phase — starting, ringing, accepting, active, ending, ended, rejected, missed, failed.
• yours — қоңырау сіздің кілтіңізге тиесілі: бағдарлама онда сөйлеп, оны аяқтай алады.
• answered — қоңырауда сөйлесіп қойған. Мұндай қоңырау қайта шырылдаса, ол берілген, жаңа қоңырау емес.
• forward — желі қызметкерлердің телефондарына шырылдатады: state (ringing, taken, missed) және taken_by — қызметкердің аты. Қызметкердің нөмірі берілмейді.
• started_at, ended_at, duration_sec — қоңырау аяқталғаннан кейінгі сөйлесу уақыты; end_reason.
• repeat — клиент бұл желіге бұрын қоңырау шалды ма, қараңыз: Қоңыраулар тарихы.

Дауыс: сөйлеу және тыңдау

1. Билет сұраңыз: POST /calls/<id>/voice/ — сіздің кілтіңіздің қоңырауы үшін. Жауапта url және expires_in (секунд).
2. Билет жарамды кезде wss://dialogs.tehprof.kz + url мекенжайына WebSocket ашыңыз.
3. Өз дыбысыңызды екілік хабарламалармен жіберіңіз — клиенттің дыбысы да солай келеді.

Не көресіз: билет сұрауының жауабында url мен expires_in келеді, ал WebSocket қосылғаннан кейін клиент дыбысы екілік хабарламалармен келеді.

• Екі жаққа пішім — PCM 16 бит (little-endian), 16 кГц, моно. Хабарлама ұзындығы жұп, 64 КиБ-тан аспайды.
• Алдын ала 2 секундқа дейін дыбыс жіберуге болады. Артығы тасталады және dropped <мс> мәтіні келеді.
• flush мәтіні жіберілген, бірақ әлі айтылмаған дыбысты тастайды: клиент сөзді бөлсе, бағдарлама бірден үнсіз қалады.
• Бір қоңырауға — бір дауыс қосылымы.

Оқиғалар

Вебхукқа. calls:voice және webhooks:manage құқықтары бар кілт өз желілерінің қоңырау оқиғаларын тіркелген мекенжайға сол X-Dialogs-Signature-V2 қолтаңбасымен алады. Денесі — { "calls": [ … ] }.

Оқиғада: event, call_id, channel_id, conversation_id, peer, direction, phase, active, end_reason, answered, occurred_at және owner — қоңырау кімдікі: operator, program (owner_key_prefix — қай кілт), forward (желі қызметкерлердің телефондарына шырылдатады), line (мысалы, кеңсе АТС-ы) немесе бос.

{ "calls": [ {
  "event": "call.ringing", "call_id": "5311", "channel_id": "12",
  "conversation_id": "9021", "peer": "77001234567",
  "direction": "in", "phase": "ringing", "active": true,
  "answered": false, "end_reason": "", "owner": "",
  "owner_key_prefix": "", "occurred_at": "2026-11-13T09:15:02.118000+00:00"
} ] }

Өз серверіңізсіз. GET /calls/ сұрауын секундына бір рет жіберіп, алдыңғы жауаппен салыстырыңыз — SDK ішіндегі api.calls.watch() осылай істейді.

Вебхук бағдарлама іске қосылмаған кезде де оқиғаларды алады: қоңырау жоғалмайды.