# MANGO OFFICE — API Виртуальной АТС: Отправить SMS и проверить баланс

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

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

1. Отправь SMS: POST /vpbx/commands/sms с from_extension — внутренним номером сотрудника (с него списываются деньги), to_number, text (до 268 кириллических символов) и sms_sender — именем отправителя из доступных в аккаунте.
2. Результат придёт на /vpbx/result/sms с тем же command_id; код 4300 значит, что SMS не отправлено.
3. Перед рассылкой проверь баланс: POST /vpbx/account/balance с пустым json {}. В ответе balance и currency.

```python
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/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/account/balance — Баланс

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

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

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

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

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

- [Позвонить клиенту из CRM одной кнопкой](https://mcp-everything.ru/integrations/mango-office/scenarios/pozvonit-klientu-iz-crm-odnoy-knopkoy.md)
- [Показывать карточку клиента при входящем звонке](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)

---

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