MANGO OFFICE — API Виртуальной АТС: Показывать карточку клиента при входящем звонке

Сценарий из mcp-everything. Актуально на 2026-10-24.

АТС сообщает о каждом звонке, а CRM открывает менеджеру карточку звонящего.

В настройках API укажи адрес своей системы для уведомлений. ВАТС будет присылать POST-запросы на /events/call с полями vpbx_api_key, sign и json.
Проверяй подпись каждого уведомления тем же способом: sha256(vpbx_api_key + json + vpbx_api_salt).
В событии — call_id, call_state (Appeared, Connected, OnHold, Disconnected), from.number, to.extension и seq. Когда звонок Appeared у сотрудника, найди клиента по from.number и покажи карточку менеджеру с этим внутренним номером.
Порядок событий не гарантирован — сортируй их по seq внутри entry_id.
Чтобы сопоставить внутренние номера с сотрудниками, получи список: POST /vpbx/config/users/request. Завершить вызов, который ещё в IVR или у абонента, можно командой POST /vpbx/commands/call/hangup с call_id из события.

import hashlib, hmac, json

def handle_event(form: dict) -> None:
    expected = hashlib.sha256((form["vpbx_api_key"] + form["json"] + SALT).encode()).hexdigest()
    if not hmac.compare_digest(expected, form["sign"]):
        return  # чужой запрос
    ev = json.loads(form["json"])
    if ev.get("call_state") == "Appeared" and ev.get("to", {}).get("extension"):
        show_client_card(manager_ext=ev["to"]["extension"], phone=ev["from"].get("number"))

Базовые URL

Боевой: https://app.mango-office.ru

Авторизация

Тип: API-ключ

Каждый запрос — POST с тремя полями формы: vpbx_api_key (уникальный код ВАТС), sign (подпись) и json (параметры команды). Подпись: sign = sha256(vpbx_api_key + json + vpbx_api_salt), где vpbx_api_salt — ключ создания подписи; сам ключ в запросах не передаётся. Уведомления, которые ВАТС отправляет во внешнюю систему, подписываются так же.

sign = sha256(vpbx_api_key + json + vpbx_api_salt)

Методы сценария

POST /vpbx/commands/call/hangup — Завершение вызова

Работает, когда вызов находится в IVR или у абонента (location = ivr или abonent).

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса
`command_id`	body	string	нет	ID команды, до 128 байт
`call_id`	body	string	да	Внутренний ID вызова (не SIP Call-ID)

Пример запроса:

{
    "command_id": "cmd.888.vpbx.12345.external.system.com.net",
    "call_id": "100500"
}

POST /vpbx/config/users/request — Список сотрудников

В ответе users: extension, name, email, department, position, номера (number, protocol, wait_sec, order, status) и др.

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса
`extension`	body	string	нет	Внутренний номер; без него — весь список
`ext_fields`	body	array	нет	Доп. поля: general.user_id, general.sips, groups, general.access_role_id, telephony.line_id и др.

Пример запроса:

{
    "extension": "1234"
}

Нюансы

Уведомления (API Realtime) ВАТС отправляет POST-запросом на адрес внешней системы, например https://external-system.com/events/call, с полями vpbx_api_key, sign, json. Есть события о вызове, результате SMS, записи разговора, DTMF, завершении вызова.
Событие events/call: entry_id (группа вызовов), call_id, timestamp, seq, call_state (Appeared, Connected, OnHold, Disconnected), location (ivr, queue, abonent), from.number, from.extension, to.number, to.extension, disconnect_reason.
Порядок событий не гарантирован — сортируйте по seq. Порядок результата команды и событий, которые она порождает, тоже не гарантирован.
Часть команд требует ID, которые приходят только через API Realtime (например, call_id).
Время в статистике и событиях — UTC+3.
Есть эмулятор API ВАТС и SHA256-генератор в разделе поддержки; при невозможности использовать API ВАТС предлагается «API Сервер-клиент».

Другие сценарии

Если этого недостаточно — официальная документация: https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/mango-office.md