MANGO OFFICE — API Виртуальной АТС API

Отрасль: Связь и уведомления. Актуально на 2026-10-24.

Основной API MANGO OFFICE для управления виртуальной АТС: команды (звонок от имени сотрудника или группы, завершение, перевод и маршрутизация вызова, SMS, запись разговора, воспроизведение файла), статистика вызовов, записи разговоров, конфигурация (сотрудники, группы, номера, SIP-учётные записи, баланс) и уведомления в реальном времени о событиях. Архитектура REST, данные — JSON.

Сценарии

Позвонить клиенту из CRM одной кнопкой

Click-to-call: менеджер нажимает на номер в CRM, АТС сначала звонит ему, потом соединяет с клиентом.

В личном кабинете 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 в подписи и в запросе — одна и та же строка.

import hashlib, json, requests

API_KEY, SALT = "<vpbx_api_key>", "<vpbx_api_salt>"

def mango(path: str, params: dict) -> dict:
    payload = json.dumps(params, ensure_ascii=False, separators=(",", ":"))
    sign = hashlib.sha256((API_KEY + payload + SALT).encode()).hexdigest()
    r = requests.post(f"https://app.mango-office.ru{path}", data={"vpbx_api_key": API_KEY, "sign": sign, "json": payload})
    return r.json()

print(mango("/vpbx/commands/callback", {"command_id": "crm-1042", "from": {"extension": "101"}, "to_number": "79991234567"}))

Показывать карточку клиента при входящем звонке

АТС сообщает о каждом звонке, а 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"))

Выгрузить статистику звонков за период

Отчёт по звонкам для аналитики: кто звонил, кому, сколько длился разговор.

Запусти формирование: POST /vpbx/stats/request с date_from и date_to в Unix-времени (период — не больше месяца) и fields — нужными полями в нужном порядке. Можно отфильтровать по сотруднику или номеру.
В ответе — key. Забирай результат: POST /vpbx/stats/result с этим key.
Ответ 204 значит, что данные ещё не готовы — повторяй не чаще раза в 5 секунд. 200 — готово: тело в CSV, разделитель «;», строки через перевод строки. 404 — ключ неверный или устарел.
Время в статистике — московское (UTC+3).

import time

job = mango("/vpbx/stats/request", {"date_from": 1761944400, "date_to": 1762549200,
                                    "fields": "start, finish, from_extension, from_number, to_extension, to_number, disconnect_reason"})
while True:
    payload = json.dumps({"key": job["key"]}, separators=(",", ":"))
    sign = hashlib.sha256((API_KEY + payload + SALT).encode()).hexdigest()
    r = requests.post("https://app.mango-office.ru/vpbx/stats/result", data={"vpbx_api_key": API_KEY, "sign": sign, "json": payload})
    if r.status_code == 200:
        rows = [line.split(";") for line in r.text.splitlines()]
        break
    time.sleep(5)

Отправить SMS и проверить баланс

SMS клиенту с номера компании — подтверждение записи, напоминание.

Отправь 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.

print(mango("/vpbx/commands/sms", {"command_id": "sms-1042", "from_extension": "101", "to_number": "79991234567",
                                   "text": "Вы записаны на 25.10 в 14:00. Ждём вас!", "sms_sender": "<имя отправителя>"}))
print(mango("/vpbx/account/balance", {}))

Базовые 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/callback — Вызов от имени сотрудника

Результат приходит во внешнюю систему на /vpbx/result/callback (command_id, result).

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса
`command_id`	body	string	нет	ID команды во внешней системе, до 128 байт
`from.extension`	body	string	да	Внутренний номер сотрудника
`from.number`	body	string	нет	Номер сотрудника, с которого звонить (SIP, FMC, ТфОП), до 128 байт
`to_number`	body	string	да	Вызываемый номер: сотрудник, группа или любой номер
`line_number`	body	string	нет	Линия (SIP UAC, 7-800, DID); для SIP — имя линии
`sip_headers`	body	object	нет	SIP-заголовки, например Call-Info/answer-after

POST /vpbx/commands/callback_group — Вызов от имени группы

Короткий номер группы указывается в from или в to.

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса
`command_id`	body	string	нет	ID команды, до 128 байт
`from`	body	string	да	Вызывающий: внешний номер или короткий номер группы
`to`	body	string	да	Вызываемый: внешний номер или короткий номер группы
`line_number`	body	string	да	Линия той же ВАТС (SIP UAC, 7-800, DID)

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

{
    "command_id": "cbk1",
    "from": "1234",
    "to": "74955404444",
    "line_number": "74951234567"
}

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/commands/sms — Отправка SMS

Результат — на /vpbx/result/sms; код 4300 — SMS не отправлено.

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса
`command_id`	body	string	нет	ID команды, до 128 байт
`text`	body	string	да	Текст: до 612 латинских или 268 кириллических символов
`from_extension`	body	string	да	Внутренний номер сотрудника (с него списываются средства)
`to_number`	body	string	да	Номер получателя, до 128 байт
`sms_sender`	body	string	нет	Имя отправителя из доступных в аккаунте

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

{
    "command_id": "smsmsmsm",
    "text": "Hello world!",
    "from_extension": "222",
    "to_number": "74955404444",
    "sms_sender": "PRO-TAXI"
}

POST /vpbx/stats/request — Запуск формирования статистики

Асинхронно: в ответе key, по нему затем забирается результат. О готовности ВАТС может уведомить на /vpbx/result/stat (key, request_id).

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса
`date_from`	body	integer	да	Начало периода, Unix time (UTC+3)
`date_to`	body	integer	да	Конец периода; не больше месяца от date_from
`fields`	body	string	нет	Поля выгрузки через запятую в нужном порядке
`from.extension`	body	string	нет	Сотрудник-инициатор
`from.number`	body	string	нет	Номер вызывающего (E.164)
`to.extension`	body	string	нет	Вызываемый сотрудник
`to.number`	body	string	нет	Вызываемый номер (E.164)
`call_party.extension`	body	string	нет	Сотрудник с любой стороны (нельзя вместе с from/to)
`call_party.number`	body	string	нет	Номер с любой стороны
`request_id`	body	string	нет	ID запроса во внешней системе, до 128 байт

POST /vpbx/stats/result — Получение статистики вызовов

200 — данные готовы (CSV-строка, разделитель ;, строки — \n), 204 — ещё не готовы (повторять не чаще раза в 5 секунд), 404 — ключ неверный или устарел.

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса
`key`	body	string	да	Ключ из stats/request

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

{
    "key": "b3ZvIt8hPJReV8v4MYspQQA=="
}

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"
}

POST /vpbx/account/balance — Баланс

Тело — пустой JSON {}.

Параметр	Где	Тип	Обяз.	Описание
`vpbx_api_key`	body	string	да	Уникальный код ВАТС
`sign`	body	string	да	Подпись запроса

Пример ответа:

{
    "result": 1000,
    "balance": 963592.45,
    "currency": "RUB",
    "response_at": "2019-01-24 17:55:24"
}

Нюансы

Уведомления (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 Сервер-клиент».

Ошибки

Код	Описание
`1000`	Действие выполнено успешно
`1100`	Вызов завершён в нормальном режиме
`2xxx`	Ограничение биллинговой системы
`3100`	Неверные параметры команды
`3101`	Запрос отправлен не методом POST
`3102`	Подпись не совпадает с вычисленной
`3103`	Нет обязательного параметра
`3200`	Неверный номер абонента
`3300`	Объект не существует
`4001`	Команда не поддерживается
`4290`	Превышено число запросов (HTTP 429)
`5001`	Перегрузка: лимит каналов или вызовов в секунду

Ограничения

Период статистики — не больше месяца.
Результат статистики хранится не меньше минуты после готовности; опрос — не чаще раза в 5 секунд.
SMS — до 612 латинских или 268 кириллических символов (4 сегмента).

Источники

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