# MANGO OFFICE — API Виртуальной АТС: Позвонить клиенту из CRM одной кнопкой

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

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

1. В личном кабинете MANGO OFFICE подключи API и возьми vpbx_api_key (уникальный код ВАТС) и vpbx_api_salt (ключ подписи). Ключ подписи никогда не передаётся в запросах.
2. Каждый запрос — POST с тремя полями формы: vpbx_api_key, json (параметры команды строкой) и sign = sha256(vpbx_api_key + json + vpbx_api_salt) в hex.
3. Запусти вызов: POST /vpbx/commands/callback с command_id (твой ID команды), from.extension — внутренним номером менеджера и to_number — номером клиента. При необходимости укажи line_number — линию, с которой звонить.
4. Результат команды придёт на твой адрес /vpbx/result/callback с тем же command_id и кодом result (1000 — успешно). 3102 значит, что подпись не совпала: проверь, что json в подписи и в запросе — одна и та же строка.

```python
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"}))
```

## Базовые 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 |

## Нюансы

- Уведомления (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://mcp-everything.ru/integrations/mango-office/scenarios/pokazyvat-kartochku-klienta-pri.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