{"name":"MANGO OFFICE — API Виртуальной АТС","vendor":"MANGO OFFICE","industry":"communications","summary":"Основной API MANGO OFFICE для управления виртуальной АТС: команды (звонок от имени сотрудника или группы, завершение, перевод и маршрутизация вызова, SMS, запись разговора, воспроизведение файла), статистика вызовов, записи разговоров, конфигурация (сотрудники, группы, номера, SIP-учётные записи, баланс) и уведомления в реальном времени о событиях. Архитектура REST, данные — JSON.","docsUrl":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/","coverage":{"included":[],"excluded":[]},"scenarios":[{"id":"pozvonit-klientu-iz-crm-odnoy-knopkoy","title":"Позвонить клиенту из CRM одной кнопкой","summary":"Click-to-call: менеджер нажимает на номер в CRM, АТС сначала звонит ему, потом соединяет с клиентом.","steps":["В личном кабинете MANGO OFFICE подключи API и возьми vpbx_api_key (уникальный код ВАТС) и vpbx_api_salt (ключ подписи). Ключ подписи никогда не передаётся в запросах.","Каждый запрос — POST с тремя полями формы: vpbx_api_key, json (параметры команды строкой) и sign = sha256(vpbx_api_key + json + vpbx_api_salt) в hex.","Запусти вызов: POST /vpbx/commands/callback с command_id (твой ID команды), from.extension — внутренним номером менеджера и to_number — номером клиента. При необходимости укажи line_number — линию, с которой звонить.","Результат команды придёт на твой адрес /vpbx/result/callback с тем же command_id и кодом result (1000 — успешно). 3102 значит, что подпись не совпала: проверь, что json в подписи и в запросе — одна и та же строка."],"code":"import hashlib, json, requests\n\nAPI_KEY, SALT = \"<vpbx_api_key>\", \"<vpbx_api_salt>\"\n\ndef mango(path: str, params: dict) -> dict:\n    payload = json.dumps(params, ensure_ascii=False, separators=(\",\", \":\"))\n    sign = hashlib.sha256((API_KEY + payload + SALT).encode()).hexdigest()\n    r = requests.post(f\"https://app.mango-office.ru{path}\", data={\"vpbx_api_key\": API_KEY, \"sign\": sign, \"json\": payload})\n    return r.json()\n\nprint(mango(\"/vpbx/commands/callback\", {\"command_id\": \"crm-1042\", \"from\": {\"extension\": \"101\"}, \"to_number\": \"79991234567\"}))","language":"python","methods":["POST /vpbx/commands/callback"]},{"id":"pokazyvat-kartochku-klienta-pri","title":"Показывать карточку клиента при входящем звонке","summary":"АТС сообщает о каждом звонке, а CRM открывает менеджеру карточку звонящего.","steps":["В настройках 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 из события."],"code":"import hashlib, hmac, json\n\ndef handle_event(form: dict) -> None:\n    expected = hashlib.sha256((form[\"vpbx_api_key\"] + form[\"json\"] + SALT).encode()).hexdigest()\n    if not hmac.compare_digest(expected, form[\"sign\"]):\n        return  # чужой запрос\n    ev = json.loads(form[\"json\"])\n    if ev.get(\"call_state\") == \"Appeared\" and ev.get(\"to\", {}).get(\"extension\"):\n        show_client_card(manager_ext=ev[\"to\"][\"extension\"], phone=ev[\"from\"].get(\"number\"))","language":"python","methods":["POST /vpbx/commands/call/hangup","POST /vpbx/config/users/request"]},{"id":"vygruzit-statistiku-zvonkov-za-period","title":"Выгрузить статистику звонков за период","summary":"Отчёт по звонкам для аналитики: кто звонил, кому, сколько длился разговор.","steps":["Запусти формирование: POST /vpbx/stats/request с date_from и date_to в Unix-времени (период — не больше месяца) и fields — нужными полями в нужном порядке. Можно отфильтровать по сотруднику или номеру.","В ответе — key. Забирай результат: POST /vpbx/stats/result с этим key.","Ответ 204 значит, что данные ещё не готовы — повторяй не чаще раза в 5 секунд. 200 — готово: тело в CSV, разделитель «;», строки через перевод строки. 404 — ключ неверный или устарел.","Время в статистике — московское (UTC+3)."],"code":"import time\n\njob = mango(\"/vpbx/stats/request\", {\"date_from\": 1761944400, \"date_to\": 1762549200,\n                                    \"fields\": \"start, finish, from_extension, from_number, to_extension, to_number, disconnect_reason\"})\nwhile True:\n    payload = json.dumps({\"key\": job[\"key\"]}, separators=(\",\", \":\"))\n    sign = hashlib.sha256((API_KEY + payload + SALT).encode()).hexdigest()\n    r = requests.post(\"https://app.mango-office.ru/vpbx/stats/result\", data={\"vpbx_api_key\": API_KEY, \"sign\": sign, \"json\": payload})\n    if r.status_code == 200:\n        rows = [line.split(\";\") for line in r.text.splitlines()]\n        break\n    time.sleep(5)","language":"python","methods":["POST /vpbx/stats/request","POST /vpbx/stats/result"]},{"id":"otpravit-sms-i-proverit-balans","title":"Отправить SMS и проверить баланс","summary":"SMS клиенту с номера компании — подтверждение записи, напоминание.","steps":["Отправь SMS: POST /vpbx/commands/sms с from_extension — внутренним номером сотрудника (с него списываются деньги), to_number, text (до 268 кириллических символов) и sms_sender — именем отправителя из доступных в аккаунте.","Результат придёт на /vpbx/result/sms с тем же command_id; код 4300 значит, что SMS не отправлено.","Перед рассылкой проверь баланс: POST /vpbx/account/balance с пустым json {}. В ответе balance и currency."],"code":"print(mango(\"/vpbx/commands/sms\", {\"command_id\": \"sms-1042\", \"from_extension\": \"101\", \"to_number\": \"79991234567\",\n                                   \"text\": \"Вы записаны на 25.10 в 14:00. Ждём вас!\", \"sms_sender\": \"<имя отправителя>\"}))\nprint(mango(\"/vpbx/account/balance\", {}))","language":"python","methods":["POST /vpbx/commands/sms","POST /vpbx/account/balance"]}],"baseUrls":[{"label":"Боевой","url":"https://app.mango-office.ru"}],"auth":{"type":"api_key","description":"Каждый запрос — POST с тремя полями формы: `vpbx_api_key` (уникальный код ВАТС), `sign` (подпись) и `json` (параметры команды). Подпись: `sign = sha256(vpbx_api_key + json + vpbx_api_salt)`, где `vpbx_api_salt` — ключ создания подписи; сам ключ в запросах не передаётся. Уведомления, которые ВАТС отправляет во внешнюю систему, подписываются так же.","example":"sign = sha256(vpbx_api_key + json + vpbx_api_salt)"},"methods":[{"id":"POST /vpbx/commands/callback","title":"Вызов от имени сотрудника","httpMethod":"POST","path":"/vpbx/commands/callback","description":"Результат приходит во внешнюю систему на `/vpbx/result/callback` (`command_id`, `result`).","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"},{"name":"command_id","in":"body","type":"string","required":false,"description":"ID команды во внешней системе, до 128 байт"},{"name":"from.extension","in":"body","type":"string","required":true,"description":"Внутренний номер сотрудника"},{"name":"from.number","in":"body","type":"string","required":false,"description":"Номер сотрудника, с которого звонить (SIP, FMC, ТфОП), до 128 байт"},{"name":"to_number","in":"body","type":"string","required":true,"description":"Вызываемый номер: сотрудник, группа или любой номер"},{"name":"line_number","in":"body","type":"string","required":false,"description":"Линия (SIP UAC, 7-800, DID); для SIP — имя линии"},{"name":"sip_headers","in":"body","type":"object","required":false,"description":"SIP-заголовки, например Call-Info/answer-after"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /vpbx/commands/callback_group","title":"Вызов от имени группы","httpMethod":"POST","path":"/vpbx/commands/callback_group","description":"Короткий номер группы указывается в `from` или в `to`.","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"},{"name":"command_id","in":"body","type":"string","required":false,"description":"ID команды, до 128 байт"},{"name":"from","in":"body","type":"string","required":true,"description":"Вызывающий: внешний номер или короткий номер группы"},{"name":"to","in":"body","type":"string","required":true,"description":"Вызываемый: внешний номер или короткий номер группы"},{"name":"line_number","in":"body","type":"string","required":true,"description":"Линия той же ВАТС (SIP UAC, 7-800, DID)"}],"requestExample":"{\n    \"command_id\": \"cbk1\",\n    \"from\": \"1234\",\n    \"to\": \"74955404444\",\n    \"line_number\": \"74951234567\"\n}","responseExample":"","docsUrl":""},{"id":"POST /vpbx/commands/call/hangup","title":"Завершение вызова","httpMethod":"POST","path":"/vpbx/commands/call/hangup","description":"Работает, когда вызов находится в IVR или у абонента (`location` = `ivr` или `abonent`).","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"},{"name":"command_id","in":"body","type":"string","required":false,"description":"ID команды, до 128 байт"},{"name":"call_id","in":"body","type":"string","required":true,"description":"Внутренний ID вызова (не SIP Call-ID)"}],"requestExample":"{\n    \"command_id\": \"cmd.888.vpbx.12345.external.system.com.net\",\n    \"call_id\": \"100500\"\n}","responseExample":"","docsUrl":""},{"id":"POST /vpbx/commands/sms","title":"Отправка SMS","httpMethod":"POST","path":"/vpbx/commands/sms","description":"Результат — на `/vpbx/result/sms`; код `4300` — SMS не отправлено.","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"},{"name":"command_id","in":"body","type":"string","required":false,"description":"ID команды, до 128 байт"},{"name":"text","in":"body","type":"string","required":true,"description":"Текст: до 612 латинских или 268 кириллических символов"},{"name":"from_extension","in":"body","type":"string","required":true,"description":"Внутренний номер сотрудника (с него списываются средства)"},{"name":"to_number","in":"body","type":"string","required":true,"description":"Номер получателя, до 128 байт"},{"name":"sms_sender","in":"body","type":"string","required":false,"description":"Имя отправителя из доступных в аккаунте"}],"requestExample":"{\n    \"command_id\": \"smsmsmsm\",\n    \"text\": \"Hello world!\",\n    \"from_extension\": \"222\",\n    \"to_number\": \"74955404444\",\n    \"sms_sender\": \"PRO-TAXI\"\n}","responseExample":"","docsUrl":""},{"id":"POST /vpbx/stats/request","title":"Запуск формирования статистики","httpMethod":"POST","path":"/vpbx/stats/request","description":"Асинхронно: в ответе `key`, по нему затем забирается результат. О готовности ВАТС может уведомить на `/vpbx/result/stat` (`key`, `request_id`).","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"},{"name":"date_from","in":"body","type":"integer","required":true,"description":"Начало периода, Unix time (UTC+3)"},{"name":"date_to","in":"body","type":"integer","required":true,"description":"Конец периода; не больше месяца от date_from"},{"name":"fields","in":"body","type":"string","required":false,"description":"Поля выгрузки через запятую в нужном порядке"},{"name":"from.extension","in":"body","type":"string","required":false,"description":"Сотрудник-инициатор"},{"name":"from.number","in":"body","type":"string","required":false,"description":"Номер вызывающего (E.164)"},{"name":"to.extension","in":"body","type":"string","required":false,"description":"Вызываемый сотрудник"},{"name":"to.number","in":"body","type":"string","required":false,"description":"Вызываемый номер (E.164)"},{"name":"call_party.extension","in":"body","type":"string","required":false,"description":"Сотрудник с любой стороны (нельзя вместе с from/to)"},{"name":"call_party.number","in":"body","type":"string","required":false,"description":"Номер с любой стороны"},{"name":"request_id","in":"body","type":"string","required":false,"description":"ID запроса во внешней системе, до 128 байт"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /vpbx/stats/result","title":"Получение статистики вызовов","httpMethod":"POST","path":"/vpbx/stats/result","description":"`200` — данные готовы (CSV-строка, разделитель `;`, строки — `\\n`), `204` — ещё не готовы (повторять не чаще раза в 5 секунд), `404` — ключ неверный или устарел.","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"},{"name":"key","in":"body","type":"string","required":true,"description":"Ключ из stats/request"}],"requestExample":"{\n    \"key\": \"b3ZvIt8hPJReV8v4MYspQQA==\"\n}","responseExample":"","docsUrl":""},{"id":"POST /vpbx/config/users/request","title":"Список сотрудников","httpMethod":"POST","path":"/vpbx/config/users/request","description":"В ответе `users`: `extension`, `name`, `email`, `department`, `position`, номера (`number`, `protocol`, `wait_sec`, `order`, `status`) и др.","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"},{"name":"extension","in":"body","type":"string","required":false,"description":"Внутренний номер; без него — весь список"},{"name":"ext_fields","in":"body","type":"array","required":false,"description":"Доп. поля: general.user_id, general.sips, groups, general.access_role_id, telephony.line_id и др."}],"requestExample":"{\n    \"extension\": \"1234\"\n}","responseExample":"","docsUrl":""},{"id":"POST /vpbx/account/balance","title":"Баланс","httpMethod":"POST","path":"/vpbx/account/balance","description":"Тело — пустой JSON `{}`.","params":[{"name":"vpbx_api_key","in":"body","type":"string","required":true,"description":"Уникальный код ВАТС"},{"name":"sign","in":"body","type":"string","required":true,"description":"Подпись запроса"}],"requestExample":"","responseExample":"{\n    \"result\": 1000,\n    \"balance\": 963592.45,\n    \"currency\": \"RUB\",\n    \"response_at\": \"2019-01-24 17:55:24\"\n}","docsUrl":""}],"codeExamples":[],"errors":[{"code":"1000","description":"Действие выполнено успешно"},{"code":"1100","description":"Вызов завершён в нормальном режиме"},{"code":"2xxx","description":"Ограничение биллинговой системы"},{"code":"3100","description":"Неверные параметры команды"},{"code":"3101","description":"Запрос отправлен не методом POST"},{"code":"3102","description":"Подпись не совпадает с вычисленной"},{"code":"3103","description":"Нет обязательного параметра"},{"code":"3200","description":"Неверный номер абонента"},{"code":"3300","description":"Объект не существует"},{"code":"4001","description":"Команда не поддерживается"},{"code":"4290","description":"Превышено число запросов (HTTP 429)"},{"code":"5001","description":"Перегрузка: лимит каналов или вызовов в секунду"}],"limits":"- Период статистики — не больше месяца.\n- Результат статистики хранится не меньше минуты после готовности; опрос — не чаще раза в 5 секунд.\n- SMS — до 612 латинских или 268 кириллических символов (4 сегмента).","gotchas":["Уведомления (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 Сервер-клиент»."],"slug":"mango-office","version":2,"updatedAt":"2026-10-24T17:05:33.877Z","sources":[{"title":"Методы API Виртуальной АТС","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"О параметре sign","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/4_obschie_polozheniya_o_vzaimodeystvii_sistem/2_4_unikalnyy_kod_vashey_vats_klyuch_dlya/2_4_3_o_parametre_sign/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Вызов от имени сотрудника","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_1_initsiirovanie_vyzova_ot_imeni/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Вызов от имени группы","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_2_initsiirovanie_vyzova_ot_imeni_gruppy/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Завершение вызова","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_3_zavershenie_vyzova/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Отправка SMS","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_4_otpravka_sms/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Запуск формирования статистики","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/4_4_api_statistika/1_4_1_zapros_bazovoy_statistiki/3_4_1_1_zapusk_formirovaniya_statistiki/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Получение статистики","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/4_4_api_statistika/1_4_1_zapros_bazovoy_statistiki/3_4_1_2_poluchenie_statistiki_vyzovov/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Список сотрудников","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/7_7_api_konfiguratsiya/3_7_1_zapros_spiska_sotrudnikov_vats/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Баланс","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/7_7_api_konfiguratsiya/3_7_6_poluchenie_balansa/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Уведомление о вызове","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/1_1_api_realtime/3_1_2_uvedomlenie_o_vyzove/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Коды результатов","url":"https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/7_spisok_kodov_rezultatov/","kind":"research","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"Вставленный текст","url":"","kind":"import","addedAt":"2026-10-19T13:40:19.749Z"},{"title":"scenarios-mango-office.md","url":"","kind":"import","addedAt":"2026-10-24T17:05:25.151Z"}],"logoUrl":null}