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

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

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

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

```python
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 Сервер-клиент».

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

- [Позвонить клиенту из CRM одной кнопкой](https://mcp-everything.ru/integrations/mango-office/scenarios/pozvonit-klientu-iz-crm-odnoy-knopkoy.md)
- [Выгрузить статистику звонков за период](https://mcp-everything.ru/integrations/mango-office/scenarios/vygruzit-statistiku-zvonkov-za-period.md)
- [Отправить SMS и проверить баланс](https://mcp-everything.ru/integrations/mango-office/scenarios/otpravit-sms-i-proverit-balans.md)

---

Если этого недостаточно — официальная документация: 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