Звонки через 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. Пока билет действует, откройте WebSocket на wss://dialogs.tehprof.kz + url.
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/ раз в секунду и сравнивайте с прошлым ответом — так делает api.calls.watch() в SDK.

Вебхук получает события и тогда, когда программа не запущена: звонок не потеряется.